NAME
POE::Thing - A POE abstraction layer for conciseness and simplicity
DESCRIPTION
POE is a very powerful and flexible system for doing asynchronous programming.
But personally, I find it confusing and tricky to use at times.
It is flexible to the point of having too much choice, has a terminology that is sometimes confusing, a tendency towards very verbose programming, and POE components aren't as easy to reuse as I would like.
To be fair, a lot of these issues are done for the sake of speed, dependency minimisation and Perl version compatibility, but sometimes speed doesn't matter so much, you can be sure of a modern Perl version, and you are more interested in expressiveness and development time.
POE::Thing is an abstraction layer implemented on a number of principles.
Object Orientation is Worth It
Although POE emphasises speed, for general usage the additional development time and flexibility gained by using OO methods is worth it for most general uses.
The Use of Modern Techniques
Techniques such as subroutines attributes can be used to make POE development much more declarative and expressive.
These techniques, and other setup-time abstractions, can also allow us to check the configuration of the objects and catch user mistakes early, reducing the number of bugs, and reducing the total code size.
Early Checking
POE can be somewhat confusing about what it does or does not allow.
It is perfectly happy to let you spell an event name incorrectly, and yet will not allow you to load POE but not run a kernel (it throws a warning instead).
Where possible, POE::Thing adds additional checking at compile time, and at constructor time (before the POE kernel is started) to catch any mistakes you make.
Conciseness
Using POE can lead to duplication, particular for cases like having to specify all your event name to subroutine bindings seperately.
As part of the simplification, POE::Thing tries to reduce the amount of typing you need to do to interact with POE directly. Ideally, you should never have to touch POE directly, and most of the nitty gritty will be hidden away.
METHODS
_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];
shift()->SUPER::_start(@_);
# 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(@_);
}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.
set_message
The set_message method is used to set or change a callback event registration after the initial creation of the object.
SUPPORT
Bugs should be always be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Twin
For other issues, or commercial enhancement or support, contact the author.
AUTHORS
Adam Kennedy <cpan@ali.as<
SEE ALSO
COPYRIGHT
Copyright (c) 2006 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.