| POE::NFA - event driven nondeterministic finite automaton |
POE::NFA - event driven nondeterministic finite automaton
# 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();
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.
See POE::Session's documentation.
create() constructor.
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() 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() constructor.
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.
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() 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() 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() 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 );
POE::NFA's predefined event fields are the same as POE::Session's with the following three exceptions.
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 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 contains the name of the machine's current state. It is not
equivalent to anything from POE::Session.
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.
POE::NFA defines four events of its own. See POE::Session's ``PREDEFINED EVENT NAMES'' section for more information about other predefined events.
See POE::Session.
See POE::Session.
See POE::Session.
See POE::Session.
See POE::Session.
Many of POE::NFA's features are taken directly from POE::Session. Please see the POE::Session manpage for more information.
The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.
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.
Please see POE for more information about authors and contributors.
| POE::NFA - event driven nondeterministic finite automaton |