POE::Declare::Object - Base class for all POE::Declare classes
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.
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.
meta
# 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.
new
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.
The Alias method returns the POE::Session alias that will be used with this object instance.
Alias
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.
'My::Class.123'
# 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.
spawn
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.
The spawned method returns true if the POE::Session for a POE::Declare object has been created, or false if not.
spawned
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
undef
The session accessor finds and returns the internal POE::Session object for this instance, or undef if the object has not been spawned.
session
The kernel method is provided as a convenience. It returns the POE::Kernel object that objects of this class will run in.
kernel
The ID is a wrapper for the equivalent POE::Session method, and returns the id number for the POE::Session.
ID
Returns an integer, or undef if the heap object has not spawned.
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.
postback
post
Returns a CODE reference, or dies if the heap object has not been spawned.
CODE
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.
callback
Please don't confuse this for a method relating to "callback events" mentioned earlier, it is not related to them.
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' ] .
lookback
[ $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.
ARRAY
The post method runs a POE kernel post for a named event for the heap object's session.
Returns void.
The call method runs a POE kernel call for a named event for the heap object's session.
call
Returns as for the particular event handler, but generally returns void.
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_set
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_adjust
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_clear
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
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.
alarm_remove_all
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_set
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.
delay_adjust
The following POE events are provided for all classes
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.
_start
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.
$_[KERNEL]
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.
_stop
sub _stop { my $self = $_[HEAP]; # Additional tasks here ... $_[0]->SUPER::_stop(@_[1..$#_]); }
The finish method is a convenience provided to simplify the process of shutting down the current object/session.
finish
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.
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.
Adam Kennedy <adamk@cpan.org>
POE, POE::Declare, http://ali.as/
Copyright 2006 - 2012 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.
To install POE::Declare, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Declare
CPAN shell
perl -MCPAN -e shell install POE::Declare
For more information on module installation, please visit the detailed CPAN module installation guide.