NAME POE::Class - a base class for everything OO POE SYNOPSIS package My::Thingy; use POE; # POE::Class is a base class use base 'POE::Class'; # None of these method are "required" but your session is not going to live # long if you do not atleast define a handler_start (which is the handler # for _start). sub handler_start { my $self = $_[OBJECT]; # This is required for object/session tracking $self->SUPER::handler_start(@_[1 .. $#_]); # do something that keeps you alive } sub handler_stop { my $self = $_[OBJECT]; # This is required for object/session tracking # and for internal cleanup $self->SUPER::handler_stop(@_[1 .. $#_]); } sub handler_child { my $self = $_[OBJECT]; # This is required for object/session tracking $self->SUPER::handler_child(@_[1 .. $#_]); } sub handler_parent { my $self = $_[OBJECT]; # This is required for object/session tracking $self->SUPER::handler_parent(@_[1 .. $#_]); } # Called from handler_start, define states we use sub create_states { my ($self) = @_; $poe_kernel->state(state_name => $self, 'handler_state_name'); } # Takes an array of key value pairs and calls # the corresponding set method (key) with the value my $self = new My::Thingy( attrib1 => "stuff", attrib2 => "more stuff" ); # Set what session type this will be $self->set_session_class("POE::Session::OtherSession"); # Create the session $self->start; # Every object has a unique ID for tracking print $self->ID, "\n"; # get your session my $session = $self->get_session; # Session/Object hierarchy # Get the objects of your child sessions my @child_objects = $self->get_child_objects; # Get your parent session object # returns undef if you have no parent my $parent = $self->get_parent_object; # Resolve a session to the object for that session # $session can be a session ID or a session object my $object = POE::Class->resolve_object($session); # Events # post an event to all your children $self->post_children(event => @args); # post an event to your parent $self->post_parent(event => @args); # - or - # Not as safe, does not check the existence of # a parent $self->get_parent_object->post(event => @args); DESCRIPTION POE::Class is a base class for making OO POE classes. This design has a one to one object relationship to a POE session, there is one object for each session. This is currently in the prototyping stages. The whole API may change tomarrow. INSTANCE METHODS Accessors configure This method is called from the default "new()" constructor. It expects an array of key value pairs. The keys should be the names of accessor methods. The value is the argument passed to the accessor method. This methods main purpose is to make it easier to set instance attributes. This method has no return value. If any of the attributes are not object methods, "configure()" will fatal. $obj->configure( attribute1 => "value1", attrib2 => "value2" ); get_session_class set_session_class This accessor sets the name of the session class to use when we create a session. The default value is *POE::Session*. This session is created when you call "start()". get_session set_session Stores the session object. Every object in this model corresponds to a session. This attribute is set inside the default "handler_start()". ID This is the unique ID for this session. It is set in the default "new()" constructor to the return of "allocate_object_id()". get_parent_object This contains the parents *object*. This attribute is set in the default "handler_parent()". undef will be returned if you have no parent. get_child_objects All children objects are tracked with the default handlers in POE::Class. This is an access only function. It returns an array of child objects. These objects are tracked in the default "handler_child()" which also relies on "resolve_session()" which relies on the default "handler_start()". get_alias set_alias This attribute is here because it is a common thing to want to do. If this is set before the session is created an alias of that name will be created for the session. This happens in "handler_start()". get_shutdown set_shutdown Another attribute here because of common use. It is simply a flag. This flag is set in "handler_shutdown" to 1. POE::Class does not use this flag, it is here because most, if not all, subclasses do use it. Sending Events/Signals These methods are only to make posting events to object sessions easier. post yield Post's an event to the object's session. The first argument should be the event name. All other arguments will be passed to the event. Returns what POE::Kernel's "post()" method returns. POE::Kernel. $self->post(event_name => "arg1", "arg2"); post_children This method sends an event to all of your children. Takes the same arguments as "post()". This method has no return value. post_parent This method sends an event to you parent if you have one. It takes the same arguments as "post()". Returns what POE::Kernel's "post()" method returns. POE::Kernel. signal Sends a signal to the session for this object. Arguments ae the same as POE::Kernel's "signal()" method minus the session. So: $obj->signal("DIE"); POE::Kernel for details on what this is doing. External Reference Counts refcount_increment refcount_decrement These methods change the recount for the object's session. The arguments are the same as POE::Kernel's methods of the same name without the session ID. So: $obj->refcount_increment("thingy"); $obj->refcount_decrement("thingy"); POE::Kernel for details on what this is doing. Startup new This is the constructor. It does not do much. First it sets the object ID using "allocate_object_id", then it calles "configure()" we have any arguments. This method blesses the object as a hash reference. If you do not want that override this in your subclass. If you do override this method be sure to set the object ID. start This method actually creates the session and returns it. The session is created with the following object states. _start => handler_start _stop => handler_stop _child => handler_child _parent => handler_parent shutdown => handler_shutdown All of these handlers exist in POE::Class so do not worry about defining them unless you want to. This method also sets the attribute parrent object to the current active sessions object. STATES POE::Class defines four default object states for POE's *special* states. _start - handler_start This method sets the attribute session to the current session and sets up session -> object tracking. If you override this method in your subclass you should call it in your method or tracking will not work. _stop - handler_stop This method free all global resources. If you override it in your subclass you must call it from your subclass (through SUPER::) or your program will leak. _child - handler_child Trackes children. _parent - handler_parent Updates parent object attribute to the new parent. CLASS METHODS Object ID Allocation These method are not needed unless you override the methods/handlers that use them. allocate_object_id Allocates a new object ID and returns it. free_object_id Free's an allocated object ID. Expect the object ID as the only argument. External Session Object Tracking resolve_session Given a session object or a session ID returns the corresponding object or undef if no object could be found. TODO Write better documentation. AUTHOR Scott Beck SEE ALSO POE