POE::Component::Supervisor(3p)

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.