1POE::NFA(3) User Contributed Perl Documentation POE::NFA(3)
2
6 POE::NFA - event driven nondeterministic finite automaton
7
9 # Import POE::NFA constants.
10 use POE::NFA;
11 # Define a machine's states, each state's events, and the coderefs
13 # that handle each event.
14 my %states = (
15 start => {
16 event_one => \&handler_one,
17 event_two => \&handler_two,
18 ...,
19 },
20 other_state => {
21 event_n => \&handler_n,
22 event_n_plus_one => \&handler_n_plus_one,
23 ...,
24 },
25 ...,
26 );
27 # Spawn an NFA and enter its initial state.
29 POE::NFA->spawn(
30 inline_states => \%states
31 )->goto_state( $start_state, $start_event );
32 # Move to a new state.
34 $machine->goto_state( $new_state, $new_event, @args );
35 # Put the current state on a stack, and move to a new one.
37 $machine->call_state( $return_event, $new_state, $new_event, @args );
38 # Move to the previous state on the call stack.
40 $machine->return_state( @returns );
41 # Forcibly stop a machine.
43 $machine->stop();
44
46 POE::NFA combines a runtime context with an event driven nondeterminis‐
47 tic finite state machine. Its main difference from POE::Session is
48 that it can embody many different states, and each state has a separate
49 group of event handlers. Events are delivered to the appropriate han‐
50 dlers in the current state only, and moving to a new state is an inex‐
51 pensive way to change what happens when an event arrives.
52 This manpage only discusses POE::NFA's differences from POE::Session.
54 It assumes a familiarity with Session's manpage, and it will refer
55 there whenever possible.
56
58 See POE::Session's documentation.
59 ID
61 See POE::Session.
62 create
64 POE::NFA does not have a create() constructor.
65 get_current_state
67 "get_current_state()" returns the name of the machine's current
68 state. This method is mainly used for getting the state of some
69 other machine. In the machine's own event handlers, it's easier to
70 just access $_[STATE].
71 get_runstate
73 "get_runstate()" returns the machine's current runstate. This is
74 equivalent to "get_heap()" in POE::Session. In the machine's own
75 handlers, it's easier to just access $_[RUNSTATE].
76 new
78 POE::NFA does not have a new() constructor.
79 spawn STATE_NAME => HANDLERS_HASHREF, ...
81 "spawn()" is POE::NFA's session constructor. It reflects the idea
82 that new state machines are spawned like threads or processes. The
83 machine itself is defined as a list of state names and hashrefs map‐
84 ping events to handlers within each state.
85 my %machine = (
87 state_1 => {
88 event_1 => \&handler_1,
89 event_2 => \&handler_2,
90 },
91 state_2 => {
92 event_1 => \&handler_3,
93 event_2 => \&handler_4,
94 },
95 );
96 Each state may define the same events. The proper handler will be
98 called depending on the machine's current state. For example, if
99 "event_1" is dispatched while the previous machine is in "state_2",
100 then &handler_3 is called to handle the event. It happens because
101 the state -> event -> handler map looks like this:
102 $machine{state_2}->{event_1} = \&handler_3;
104 The spawn() method currently only accepts "inline_states" and
106 "options". Others will be added as necessary.
107 option
109 See POE::Session.
110 postback
112 See POE::Session.
113 callback
115 See POE::Session.
116 goto_state NEW_STATE
118 goto_state NEW_STATE, ENTRY_EVENT
119 goto_state NEW_STATE, ENTRY_EVENT, EVENT_ARGS
120 "goto_state" puts the machine into a new state. If an ENTRY_EVENT is
121 specified, then that event will be dispatched when the machine enters
122 the new state. EVENT_ARGS, if included, will be passed to the entry
123 event's handler via "ARG0..$#_".
124 my $machine = $_[MACHINE];
126 $machine->goto_state( 'next_state' );
127 $machine->goto_state( 'next_state', 'call_this_event' );
128 $machine->goto_state( 'next_state', 'call_this_event', @with_these_args );
129 stop
131 "stop()" forces a machine to stop. It's similar to posting "_stop"
132 to the machine, but it performs some extra NFA cleanup. The machine
133 will also stop gracefully if it runs out of things to do, just like
134 POE::Session.
135 "stop()" is heavy-handed. It will force resource cleanup. Circular
137 references in the machine's "RUNSTATE" are not POE's responsibility
138 and may cause memory leaks.
139 $_[MACHINE]->stop();
141 call_state RETURN_EVENT, NEW_STATE
143 call_state RETURN_EVENT, NEW_STATE, ENTRY_EVENT
144 call_state RETURN_EVENT, NEW_STATE, ENTRY_EVENT, EVENT_ARGS
145 "call_state()" is similar to "goto_state()", but it pushes the cur‐
146 rent state on a stack. At some point a "return_state()" call will
147 pop the saved state and cause the machine to return there.
148 "call_state()" accepts one parameter different from "goto_state()",
150 and that is "RETURN_EVENT". "RETURN_EVENT" specifies the event to
151 emit when the machine returns to the calling state. That is, the
152 called state returns to the caller's "RETURN_EVENT" handler. The
153 "RETURN_EVENT" handler receives "return_states()"'s "RETURN_ARGS" via
154 "ARG0..$#_".
155 $machine->call_state( 'return_here', 'new_state', 'entry_event' );
157 As with "goto_state()", "ENTRY_EVENT" is the event that will be emit‐
159 ted once the machine enters its new state. "ENTRY_ARGS" are parame‐
160 ters passed to the "ENTRY_EVENT" handler via "ARG0..$#_".
161 return_state
163 return_state RETURN_ARGS
164 "return_state()" returns to the most recent state which called
165 "call_state()", optionally invoking the calling state's
166 "RETURN_EVENT", possibly with "RETURN_ARGS" passed to it via
167 "ARG0..$#_".
168 $_[MACHINE]->return_state( );
170 $_[MACHINE]->return_state( 'success', $success_value );
171
173 POE::NFA's predefined event fields are the same as POE::Session's with
174 the following three exceptions.
175 MACHINE
177 "MACHINE" is equivalent to Session's "SESSION" field. It hold a ref‐
178 erence to the current state machine, and it's useful for calling
179 methods on it. See POE::Session's "SESSION" field for more informa‐
180 tion.
181 $_[MACHINE]->goto_state( $next_state, $next_state_entry_event );
183 RUNSTATE
185 "RUNSTATE" is equivalent to Session's "HEAP" field. It holds an
186 anonymous hash reference which POE is guaranteed not to touch. See
187 POE::Session's "HEAP" field for more information.
188 STATE
190 "STATE" contains the name of the machine's current state. It is not
191 equivalent to anything from POE::Session.
192 EVENT
194 "EVENT" is equivalent to Session's "STATE" field. It holds the name
195 of the event which invoked the current handler. See POE::Session's
196 "STATE" field for more information.
197
199 POE::NFA defines four events of its own. See POE::Session's "PREDE‐
200 FINED EVENT NAMES" section for more information about other predefined
201 events.
202 poe_nfa_goto_state
204 poe_nfa_pop_state
205 poe_nfa_push_state
206 poe_nfa_stop
207 POE::NFA uses these states internally to manage state transitions and
208 stopping the machine in an orderly fashion. There may be others in
209 the future, and they will all follow the /^poe_nfa_/ naming conven‐
210 tion. To avoid conflicts, please don't define events beginning with
211 "poe_nfa_".
212
214 States' Return Values
215 See POE::Session.
217 Resource Tracking
219 See POE::Session.
221 Synchronous and Asynchronous Events
223 See POE::Session.
225 Postbacks
227 See POE::Session.
229 Job Control and Family Values
231 See POE::Session.
233
235 Many of POE::NFA's features are taken directly from POE::Session.
236 Please see POE::Session for more information.
237 The SEE ALSO section in POE contains a table of contents covering the
239 entire POE distribution.
240
242 See POE::Session's documentation.
243 Object and package states aren't implemented. Some other stuff is just
245 lashed together with twine. POE::NFA needs some more work. Please
246 send comments and suggestions to bug-poe@rt.cpan.org. Thank you.
247
249 Please see POE for more information about authors and contributors.
250perl v5.8.8 2006-09-01 POE::NFA(3)