NAME

POE::Component::Supervisor - Erlang-inspired babysitting

VERSION

version 0.09

SYNOPSIS

use POE;

use POE::Component::Supervisor;

POE::Component::Supervisor->new(
    children => [
        POE::Component::Supervisor::Supervised::Proc->new( ... ),    # monitor UNIX procs
        POE::Component::Supervisor::Supervised::Session->new( ... ), # monitor POE sessions
    ],
);

DESCRIPTION

This is a port of the Erlang process supervisor (http://www.erlang.org/doc/design_principles/sup_princ.html).

This will monitor instances of children, restarting them as necessary should they exit.

Restart throttling is not yet implemented but planned for a future version.

OBJECT HIERARCHY

A supervisor has any number of supervised child descriptors, which in turn instantiate handles for each spawned instance of the child.

Supervised children are essential object factories for handles. They spawn new instances of the child they describe by instantiating handles.

A handle will do the actual management of the child, sending events to the supervisor when the child is terminated, and also facilitate explicit termination of the child's instance.

Based on its restart_policy the supervisor may order other handles to also stop, and ask various child descriptors to respawn certain children.

POE REFERENCE COUNTING

When no more children are being supervised the POE reference count for the supervisor's session will go down to zero. If no alias is set up then the session will close. If an alias is set and no other sessions are doing anything the session will also close. See POE, and MooseX::POE::Aliased.

ATTRIBUTES

alias

See MooseX::POE::Aliased.

This defaults to undef, unlike the role, so that a supervisor session will close automatically once it has no more children to supervise.

use_logger_singleton

See MooseX::LogDispatch.

Changes the default to true, to allow usage of an already configured Log::Dispatch::Config setup.

restart_policy

This is one of one, all or rest.

If the POE::Component::Supervisor::Supervised object describing the child deems the child should be restarted, then the value of this attribute controls which other children to also restart.

one denotes that only the child which died will be restarted.

rest will cause all the children appearing after the child which died in the children array to be restarted, but not the children preceding it.

all will restart all the children.

children

This is the array of children being supervised.

It is a required argument.

Note that the array reference will be modified if new children are introduced and when children are removed (even during normal shutdown), so pass in a copy of an array if this is a problem for you.

The order of the children matters, see restart_policy.

METHODS

new %args

start @children

Spawn and supervise the children described by the descriptors in @children.

stop [ @children ]

Stop the specified children.

If no arguments are provided all the children are stopped.

should_restart_child $child, %args

Delegates to $child by calling "should_restart" in POE::Component::Supervisor::Supervised.

child_exit_is_fatal

Currently always returns false. In the future restart throttling will be implemented using this method.

If true is returned an error will be thrown by the supervisor.

EVENTS

The POE event API is currently internal. All manipulation of the supervisor object should be done using the API described in METHODS.

SEE ALSO

http://www.erlang.org/doc/design_principles/sup_princ.html

AUTHOR

Stevan Little <stevan@iinteractive.com>

Yuval Kogman <yuval.kogman@iinteractive.com<gt>

COPYRIGHT

Copyright (c) 2008, 2010 Infinity Interactive, Yuval Kogman. All rights
reserved This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.