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

NAME

POE::Declare::Object - Base class for all POE::Declare classes

DESCRIPTION

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

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

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

The session 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_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.

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_remove_all

The alarm_remove_all method is equivalent to the POE::Kernel method of the same name, removing all alarms for the heap object's session.

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 MUST 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
    ...

    $_[0]->SUPER::_stop(@_[1..$#_]);
}

finish

The finish method is a convenience provided to simplify the process of shutting down the current object/session.

It will automatically clean up as many things as possible from your session, leaving it in a state where the session will shut down as soon as the final outstanding event is processed.

Currently, this consists of removing any pending alarms and removing the session alias.

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 - 2011 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.