Adam Kennedy > POE-Declare-0.59 > POE::Declare::Object

Download:
POE-Declare-0.59.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.59   Source  

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

syntax highlighting: