NAME

Reflex::Collection - Autmatically manage a collection of collectible objects

VERSION

version 0.088

SYNOPSIS

        package TcpEchoServer;

        use Moose;
        extends 'Reflex::Listener';
        use Reflex::Collection;
        use EchoStream;

        # From Reflex::Collection.
        has_many clients => (
                handles => { remember_client => "remember" },
        );

        sub on_listener_accepted {
                my ($self, $args) = @_;
                $self->remember_client(
                        EchoStream->new(
                                handle => $args->{socket},
                                rd     => 1,
                        )
                );
        }

        1;

DESCRIPTION

Some object manage collections of collectible objects---ones that consume Reflex::Role::Collectible. For example, network servers must track objects that represent client connections. If not, those objects would go out of scope, destruct, and disconnect their clients.

Reflex::Collection is a generic object collection manager. It exposes remember() and forget(), which may be mapped to other methods using Moose's "handles" aspect.

Reflex::Collection goes beyond this simple hash-like interface. It will automatically forget() objects that emit "stopped" events, triggering their destruction if nothing else refers to them. This eliminates a large amount of repetitive work.

Reflex::Role::Collectible provides a stopped() method that emits the "stopped" event. Calling <$self-stopped()>> in the collectible class is sufficient to trigger the proper cleanup.

TODO - Reflex::Collection is an excellent place to manage pools of objects. Provide a callback interface for pulling new objects as needed.

has_many

Reflex::Collection exports the has_many() function, which works like Moose's has() with "is", "isa", "lazy" and "default" set to common values. For example:

        has_many connections => (
                handles => { remember_connection => "remember" },
        );

... is equivalent to:

        has connections => (
                # Defaults provided by has_many.
                is      => 'ro',
                isa     => 'Reflex::Collection',
                lazy    => 1,
                default => sub { Reflex::Collection->new() {,

                # Customization.
                handles => { remember_connection => "remember" },
        );

new

Create a new Reflex::Collection. It takes no parameters.

remember

Remember an object. Reflex::Collection works best if it contains the only references to the objects it manages, so you may often see objects remembered while they're constructed. See the SYNOPSIS for one such example.

remember() takes one parameter: the object to remember.

forget

Forget an object, returning its reference. You've supplied the reference, so the returned one is usually redundant. forget() takes one parameter: the object to forget.

SEE ALSO

Reflex

"ACKNOWLEDGEMENTS" in Reflex "ASSISTANCE" in Reflex "AUTHORS" in Reflex "BUGS" in Reflex "BUGS" in Reflex "CONTRIBUTORS" in Reflex "COPYRIGHT" in Reflex "LICENSE" in Reflex "TODO" in Reflex