/ 
POE-Declare-0.23_01
River stage one • 6 direct dependents • 7 total dependents
/ POE::Declare::Object

NAME

POE::Declare::Object - Base object for POE::Declare classes

DESCRIPTION

POE::Declare::Object provides the base package that delivers the core functionality for all instantiated POE::Declare objects.

Functionality and methods defined here are available in all POE::Declare objects.

METHODS

meta

The meta method can be run on either a class or instances of that class, and returns the POE::Declare::Meta metadata object for that class.

new

# Create an object, but do not spawn it
my $object = My::Class->new(
    Param1 => 'value',
    Param2 => 'value',
);

The new constructor is used to create a POE::Declare component WITHOUT immediately starting it up.

This is typically assemble to build heirachies of interlinked components and services, without the need to start all of them simultaneously.

Instead, a startup routine in the top object of the heirachy can undertake a controlled startup process, bootstrapping each piece of the overall application.

All constructors take a series of named params and return a new instance, or throw an exception on error.

Alias

The Alias method returns the POE::Session alias that will be used with this object instance.

These will typically be of the form 'My::Class.123' but may be a different value if a custom Alias param has been explicitly passed to the constructor.

spawn

# Spawn (i.e. startup) an existing object
$object->spawn;

# Create the start the object in one call
my $alias = My::Class->spawn(
    Param1 => 'value',
    Param2 => 'value',
);

The spawn method is used to create the POE::Session for this object.

It returns the session alias as a convenience, or throws an exception on error.

When called on the class instead of an object, it provides a shortcut method for a one-shot construction and spawning of an object, returning the object instead of the session alias.

Throws an exception on error.

spawned

The spawned method returns true if the POE::Session for a POE::Declare object has been created, or false if not.

session_id

The session_id accessor finds and returns the internal POE::Session id for this instance, or undef if the object has not been spawned.

session_id

The session_id accessor finds and returns the internal POE::Session object for this instance, or undef if the object has not been spawned.

kernel

The kernel method is provided as a convenience. It returns the POE::Kernel object that objects of this class will run in.

ID

The ID is a wrapper for the equivalent POE::Session method, and returns the id number for the POE::Session.

Returns an integer, or undef if the heap object has not spawned.

postback

my $handler = $object->postback(
    'event_name',
    $first_param,
    'second_param',
);
$handler->( $third_param, $first_param );

The postback method is a wrapper for the equivalent POE::Session method, and creates an anonymous subroutine that triggers a post for a named event of the heap object.

Returns a CODE reference, or dies if the heap object has not been spawned.

callback

my $handler = $object->callback(
    'event_name',
    $first_param,
    'second_param',
);
$handler->( $third_param, $first_param );

The callback method is a wrapper for the equivalent POE::Session method, and creates an anonymous subroutine that triggers a post for a named event of the heap object.

Please don't confuse this for a method relating to "callback events" mentioned earlier, it is not related to them.

Returns a CODE reference, or dies if the heap object has not been spawned.

lookback

sub create_foo {
    my $self  = shift;
    my $thing = Other::Class->new(
         ConnectEvent => $self->lookback('it_connected'),
         ConnectError => $self->lookback('it_failed'),
    );

    ...
}

The lookback method is a safe alias for [ $self-Alias, 'event_name' ] >.

When creating the lookback, the name will be double checked to verify that the handler actually exists and is registered.

Returns a reference to an ARRAY containing the heap object's alias and the event name.

post

The post method runs a POE kernel post for a named event for the heap object's session.

Returns void.

call

The call method runs a POE kernel call for a named event for the heap object's session.

Returns as for the particular event handler, but generally returns void.

alarm_set

The alarm_set method is equivalent to the POE::Kernel method of the same name, setting an alarm for a named event of the heap object's session.

alarm_adjust

The alarm_adjust method is equivalent to the POE::Kernel method of the same name, adjusting an alarm for a named event of the heap object's session.

alarm_remove

The alarm_remove method is equivalent to the POE::Kernel method of the same name, removing an alarm for a named event of the heap object's session.

alarm_clear

The alarm_clear method is a convenience method. It takes the name of a hash key for the object, containing a timer id. If the ID is set, it is cleared. If not, the method shortcuts.

delay_set

The delay_set method is equivalent to the POE::Kernel method of the same name, setting a delayed alarm for a named event of the heap object's session.

delay_adjust

The delay_adjust method is equivalent to the POE::Kernel method of the same name, adjusting a delayed alarm for a named event of the heap object's session.

EVENTS

The following POE events are provided for all classes

_start

The default _start implementation is used to register the alias for the heap object with the kernel. As such, if you need to do your own tasks in _start you should always call it first.

sub _start {
    my $self = $_[HEAP];
    $_[0]->SUPER::_start(@_[1..$#_]);

    # Additional tasks here
    ...
}

Please note though that the super call will break @_ in the current subroutine, and so you should not use $_[KERNEL] style expressions after the SUPER call.

_stop

The default _stop implementation is used to clean up our resources and aliases in the kernel. As such, if you need to do your own tasks in _stop you should always do them first and then call the SUPER last.

sub _stop {
    my $self = $_[HEAP];

    # Additional tasks here
    ...

    shift->SUPER::_stop(@_);
}

_alias_set

During the period in which a POE::Declare object is active, it will register an alias with the POE kernel (so that the session will not be cleaned up if it has no queued events of it's own and it only waiting for other sessions to send it a message).

The _alias_set method (which takes no parameters) will set the alias for the current object. This will be done automatically for you during the spawn process (in the _start event).

_alias_remove

Each POE::Declare object has a POE session and a unique alias, which is registered with the POE core when it is spawned.

Even if no events, timers, callbacks or handles are registered for the session, the existance of the alias will keep the session alive.

The _alias_remove event is used to trigger the stopping of the session as soon as all currently live events have been cleared.

This method is usually called at the beginning of a shutdown process, to indicate that the session is no longer permanent and should shutdown when possible.

SUPPORT

Bugs should be always be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Declare

For other issues, or commercial enhancement or support, contact the author.

AUTHORS

Adam Kennedy <adamk@cpan.org>

SEE ALSO

POE, POE::Declare, http://ali.as/

COPYRIGHT

Copyright 2006 - 2009 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.