Linux Certif

Toute la documentation sur la certification Linux LPI

POE::NFA.3pm

NAME

POE::NFA - event driven nondeterministic finite automaton

SYNOPSIS

   # Import POE::NFA constants.
   use POE::NFA;
 
   # Define a machine's states, each state's events, and the coderefs
   # that handle each event.
   my %states = (
     start => {
       event_one => \&handler_one,
       event_two => \&handler_two,
       ...,
     },
     other_state => {
       event_n          => \&handler_n,
       event_n_plus_one => \&handler_n_plus_one,
       ...,
     },
     ...,
   );
 
   # Spawn an NFA and enter its initial state.
   POE::NFA->spawn(
     inline_states => \%states
   )->goto_state( $start_state, $start_event );
 
   # Move to a new state.
   $machine->goto_state( $new_state, $new_event, @args );
 
   # Put the current state on a stack, and move to a new one.
   $machine->call_state( $return_event, $new_state, $new_event, @args );
 
   # Move to the previous state on the call stack.
   $machine->return_state( @returns );
 
   # Forcibly stop a machine.
   $machine->stop();
 
 

DESCRIPTION

POE::NFA combines a runtime context with an event driven nondeterministic finite state machine. Its main difference from POE::Session is that it can embody many different states, and each state has a separate group of event handlers. Events are delivered to the appropriate handlers in the current state only, and moving to a new state is an inexpensive way to change what happens when an event arrives.

This manpage only discusses POE::NFA's differences from POE::Session. It assumes a familiarity with Session's manpage, and it will refer there whenever possible.

PUBLIC METHODS

See POE::Session's documentation.

ID

See POE::Session.

create

POE::NFA does not have a create() constructor.

get_current_state

"get_current_state()" returns the name of the machine's current state. This method is mainly used for getting the state of some other machine. In the machine's own event handlers, it's easier to just access $_[STATE].

get_runstate

"get_runstate()" returns the machine's current runstate. This is equivalent to "get_heap()" in POE::Session. In the machine's own handlers, it's easier to just access $_[RUNSTATE].

new

POE::NFA does not have a new() constructor.

spawn STATE_NAME => HANDLERS_HASHREF, ...

"spawn()" is POE::NFA's session constructor. It reflects the idea that new state machines are spawned like threads or processes. The machine itself is defined as a list of state names and hashrefs mapping events to handlers within each state.

   my %machine = (
     state_1 => {
       event_1 => \&handler_1,
       event_2 => \&handler_2,
     },
     state_2 => {
       event_1 => \&handler_3,
       event_2 => \&handler_4,
     },
   );
 
 

Each state may define the same events. The proper handler will be called depending on the machine's current state. For example, if "event_1" is dispatched while the previous machine is in "state_2", then &handler_3 is called to handle the event. It happens because the state -> event -> handler map looks like this:

   $machine{state_2}->{event_1} = \&handler_3;
 
 

The spawn() method currently only accepts "inline_states" and "options". Others will be added as necessary.

option

See POE::Session.

postback

See POE::Session.

callback

See POE::Session.

goto_state NEW_STATE

goto_state NEW_STATE, ENTRY_EVENT

goto_state NEW_STATE, ENTRY_EVENT, EVENT_ARGS

"goto_state" puts the machine into a new state. If an ENTRY_EVENT is specified, then that event will be dispatched when the machine enters the new state. EVENT_ARGS, if included, will be passed to the entry event's handler via "ARG0..$#_".

   my $machine = $_[MACHINE];
   $machine->goto_state( 'next_state' );
   $machine->goto_state( 'next_state', 'call_this_event' );
   $machine->goto_state( 'next_state', 'call_this_event', @with_these_args );
 
 

stop

"stop()" forces a machine to stop. It's similar to posting "_stop" to the machine, but it performs some extra NFA cleanup. The machine will also stop gracefully if it runs out of things to do, just like POE::Session.

"stop()" is heavy-handed. It will force resource cleanup. Circular references in the machine's "RUNSTATE" are not POE's responsibility and may cause memory leaks.

   $_[MACHINE]->stop();
 
 

call_state RETURN_EVENT, NEW_STATE

call_state RETURN_EVENT, NEW_STATE, ENTRY_EVENT

call_state RETURN_EVENT, NEW_STATE, ENTRY_EVENT, EVENT_ARGS

"call_state()" is similar to "goto_state()", but it pushes the current state on a stack. At some point a "return_state()" call will pop the saved state and cause the machine to return there.

"call_state()" accepts one parameter different from "goto_state()", and that is "RETURN_EVENT". "RETURN_EVENT" specifies the event to emit when the machine returns to the calling state. That is, the called state returns to the caller's "RETURN_EVENT" handler. The "RETURN_EVENT" handler receives "return_states()"'s "RETURN_ARGS" via "ARG0..$#_".

   $machine->call_state( 'return_here', 'new_state', 'entry_event' );
 
 

As with "goto_state()", "ENTRY_EVENT" is the event that will be emitted once the machine enters its new state. "ENTRY_ARGS" are parameters passed to the "ENTRY_EVENT" handler via "ARG0..$#_".

return_state

return_state RETURN_ARGS

"return_state()" returns to the most recent state which called "call_state()", optionally invoking the calling state's "RETURN_EVENT", possibly with "RETURN_ARGS" passed to it via "ARG0..$#_".

   $_[MACHINE]->return_state( );
   $_[MACHINE]->return_state( 'success', $success_value );
 
 

PREDEFINED EVENT FIELDS

POE::NFA's predefined event fields are the same as POE::Session's with the following three exceptions.

MACHINE

"MACHINE" is equivalent to Session's "SESSION" field. It hold a reference to the current state machine, and it's useful for calling methods on it. See POE::Session's "SESSION" field for more information.

   $_[MACHINE]->goto_state( $next_state, $next_state_entry_event );
 
 

RUNSTATE

"RUNSTATE" is equivalent to Session's "HEAP" field. It holds an anonymous hash reference which POE is guaranteed not to touch. See POE::Session's "HEAP" field for more information.

STATE

"STATE" contains the name of the machine's current state. It is not equivalent to anything from POE::Session.

EVENT

"EVENT" is equivalent to Session's "STATE" field. It holds the name of the event which invoked the current handler. See POE::Session's "STATE" field for more information.

PREDEFINED EVENT NAMES

POE::NFA defines four events of its own. See POE::Session's ``PREDEFINED EVENT NAMES'' section for more information about other predefined events.

poe_nfa_goto_state

poe_nfa_pop_state

poe_nfa_push_state

poe_nfa_stop

POE::NFA uses these states internally to manage state transitions and stopping the machine in an orderly fashion. There may be others in the future, and they will all follow the /^poe_nfa_/ naming convention. To avoid conflicts, please don't define events beginning with ``poe_nfa_''.

MISCELLANEOUS CONCEPTS

States' Return Values

See POE::Session.

Resource Tracking

See POE::Session.

Synchronous and Asynchronous Events

See POE::Session.

Postbacks

See POE::Session.

Job Control and Family Values

See POE::Session.

SEE ALSO

Many of POE::NFA's features are taken directly from POE::Session. Please see POE::Session for more information.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

See POE::Session's documentation.

Object and package states aren't implemented. Some other stuff is just lashed together with twine. POE::NFA needs some more work. Please send comments and suggestions to bug-poe@rt.cpan.org. Thank you.

AUTHORS & COPYRIGHTS

Please see POE for more information about authors and contributors.