NAME

POE::Session::Attribute - Use attributes to define your POE Sessions

SYNOPSIS

  # in Some/Module.pm

  package Some::Module ;
  use base qw(POE::Session::Attribute) ;
  use POE ;

  sub _start : Package {   # package state
      my ($pkg, @args) = @_[OBJECT, ARG0 .. $#_] ;
      ...
  }

  sub stop : Object(_stop) {     # object state, explicit state name
      my ($self, ...) = @_[OBJECT, ...] ;
      ...
  }

  sub some_other_event : Inline {  # inline state
      print "boo hoo\n" ;
  }

  ...
  1 ;

  # meanwhile, in some other file

  use Some::Module ;
  use POE ;

  my $new_session_id =
      Some::Module->spawn("your", {arguments => "here"}) ;

  # or
  my $new_session_id = Some::Module->create(
	  heap => [],
	  args => ["your", {arguments => "here"}]
  ) ;

  ...

  POE::Kernel->run() ;

  # Inheritance works, too
  package Some::Module::Subclass ;
  use base qw(Some::Module) ;

  sub _stop : Object {
      my ($self, @rest) = @_ ;
      do_some_local_cleanup() ;
      $self->SUPER::_stop(@rest) ;  # you can call parent method, too
  }

DESCRIPTION

This module's purpose is to save you some boilerplate code around POE::Session->create() method. Just inherit your class from POE::Session::Attribute and define some states using attributes. Method spawn() in your package will be provided by POE::Session::Attribute (of course, you can override it, if any).

POE::Session::Attribute tries to be reasonably compatible with POE::Session::AttributeBased. As for now, all material test cases from POE::Session::AttributeBased distribution v0.03 run without errors with POE::Session::Attribute.

ATTRIBUTES

sub your_sub : Package

sub your_sub : Package(name, more_names, ...)

Makes a package state. If name is specified, it will be used as a state name. You can specify several names here. Otherwise, the name of your subroutine ("your_sub") will be used as state name.

sub your_sub : Inline

sub your_sub : Inline(name, more_names, ...)

Makes an inline state. If name is specified, it will be used as a state name. You can specify several names here. Otherwise, the name of your subroutine ("your_sub") will be used as state name.

sub your_sub : state

Same as Inline. Added for compatibility with POE::Session::AttributeBased.

sub your_sub : Object

sub your_sub : Object(name, more_names, ...)

Makes an object state. If name is specified, it will be used as a state name. You can specify several names here. Otherwise, the name of your subroutine ("your_sub") will be used as state name.

An instance of your class will be created by create() method, if at least one Object state is defined in your package. Method new() from your package will be called to create the instance. Arguments for the call to new() will be the same as specified for spawn() call (or, in other words, the same as args key to create() method, see below).

METHODS

new()

POE::Session::Attribute provides a default constructor (bless {}, $class). You can (and probably should) override it in your inheriting class. new() will be called by spawn() if at least one Object state is defined.

create([same as for POE::Session->create()])

Creates a new POE::Session based on your class/package. Accepts the same arguments as POE::Session->create() method (see POE::Session). You probably should not specify any of inline_states, object_states and package_states, because they will be constructed automatically from your code attributes.

If you have Object states in your class, create() will call new() method from your class to construct a class instance. args (from create() arguments) will be used as an argument list for this call.

Yes, it's probably somewhat messy. Suggest a fix.

When called in scalar context, returns a reference to a newly created POE::Session (but make sure to read POE::Session documentation to see why you shouldn't use it). In list context, returns a reference to POE::Session and a reference to a newly created instance of your class (in case it was really created).

spawn(@argument_list)

Same as create(args => [ @argument_list ])

SEE ALSO

POE, POE::Session, attributes, Attribute::Handlers.

There is a somewhat similar module on CPAN, POE::Session::AttributeBased. POE::Session::Attribute is pretty much API-compatible with it.

AUTHOR

dmitry kim, <dmitry.kim(at)gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by dmitry kim

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.