1POE::Kernel(3) User Contributed Perl Documentation POE::Kernel(3)
2
6 POE::Kernel - an event driven threaded application kernel in Perl
7
9 POE comes with its own event loop, which is based on select() and writ‐
10 ten entirely in Perl. To use it, simply:
11 use POE;
13 POE can adapt itself to work with other event loops and I/O multiplex
15 systems. Currently it adapts to Gtk, Tk, Event.pm, or IO::Poll when
16 one of those modules is used before POE::Kernel.
17 use Gtk; # Or Tk, Event, or IO::Poll;
19 use POE;
20 or
22 use POE qw(Loop::Gtk);
24 or
26 use POE::Kernel { loop => "Gtk" };
28 use POE::Session;
29 Methods to manage the process' global Kernel instance:
31 # Retrieve the kernel's unique identifier.
33 $kernel_id = $kernel->ID;
34 # Run the event loop, only returning when it has no more sessions to
36 # dispatch events to. Supports two forms.
37 $poe_kernel->run();
38 POE::Kernel->run();
39 FIFO event methods:
41 # Post an event to an arbitrary session.
43 $kernel->post( $session, $event, @event_args );
44 # Post an event back to the current session.
46 $kernel->yield( $event, @event_args );
47 # Call an event handler synchronously. Bypasses POE's event queue
49 # and returns the handler's return value.
50 $handler_result = $kernel->call( $session, $event, @event_args );
51 Original alarm and delay methods:
53 # Post an event which will be delivered at a given Unix epoch time.
55 # This clears previous timed events with the same state name.
56 $kernel->alarm( $event, $epoch_time, @event_args );
57 # Post an additional alarm, leaving existing ones in the queue.
59 $kernel->alarm_add( $event, $epoch_time, @event_args );
60 # Post an event which will be delivered after a delay, specified in
62 # seconds hence. This clears previous timed events with the same
63 # name.
64 $kernel->delay( $event, $seconds, @event_args );
65 # Post an additional delay, leaving existing ones in the queue.
67 $kernel->delay_add( $event, $seconds, @event_args );
68 June 2001 alarm and delay methods:
70 # Post an event which will be delivered at a given Unix epoch
72 # time. This does not clear previous events with the same name.
73 $alarm_id = $kernel->alarm_set( $event, $epoch_time, @etc );
74 # Post an event which will be delivered a number of seconds hence.
76 # This does not clear previous events with the same name.
77 $alarm_id = $kernel->delay_set( $event, $seconds_hence, @etc );
78 # Adjust an existing alarm by a number of seconds.
80 $kernel->alarm_adjust( $alarm_id, $number_of_seconds );
81 # Refresh an existing delay to a number of seconds in the future.
83 $kernel->delay_adjust( $delay_id, $number_of_seconds_hence );
84 # Remove a specific alarm, regardless whether it shares a name with
86 # others.
87 $kernel->alarm_remove( $alarm_id );
88 # Remove all alarms for the current session.
90 $kernel->alarm_remove_all( );
91 Symbolic name, or session alias methods:
93 # Set an alias for the current session.
95 $status = $kernel->alias_set( $alias );
96 # Clear an alias for the current session:
98 $status = $kernel->alias_remove( $alias );
99 # Resolve an alias into a session reference. Most POE::Kernel
101 # methods do this for you.
102 $session_reference = $kernel->alias_resolve( $alias );
103 # Resolve a session ID to a session reference. The alias_resolve
105 # method does this as well, but this is faster.
106 $session_reference = $kernel->ID_id_to_session( $session_id );
107 # Return a session ID for a session reference. It is functionally
109 # equivalent to $session->ID.
110 $session_id = $kernel->ID_session_to_id( $session_reference );
111 # Return a list of aliases for a session (or the current one, by
113 # default).
114 @aliases = $kernel->alias_list( $session );
115 Filehandle watcher methods:
117 # Watch for read readiness on a filehandle.
119 $kernel->select_read( $file_handle, $event, @optional_args );
120 # Stop watching a filehandle for read-readiness.
122 $kernel->select_read( $file_handle );
123 # Watch for write readiness on a filehandle.
125 $kernel->select_write( $file_handle, $event, @optional_args );
126 # Stop watching a filehandle for write-readiness.
128 $kernel->select_write( $file_handle );
129 # Watch for out-of-bound (expedited) read readiness on a filehandle.
131 $kernel->select_expedite( $file_handle, $event, @optional_args );
132 # Stop watching a filehandle for out-of-bound data.
134 $kernel->select_expedite( $file_handle );
135 # Pause and resume write readiness watching. These have lower
137 # overhead than full select_write() calls.
138 $kernel->select_pause_write( $file_handle );
139 $kernel->select_resume_write( $file_handle );
140 # Pause and resume read readiness watching. These have lower
142 # overhead than full select_read() calls.
143 $kernel->select_pause_read( $file_handle );
144 $kernel->select_resume_read( $file_handle );
145 # Set and/or clear a combination of selects in one call.
147 $kernel->select( $file_handle,
148 $read_event, # or undef to clear it
149 $write_event, # or undef to clear it
150 $expedite_event, # or undef to clear it
151 @optional_args,
152 );
153 Signal watcher and generator methods:
155 # Watch for a signal, and generate an event when it arrives.
157 $kernel->sig( $signal_name, $event );
158 # Stop watching for a signal.
160 $kernel->sig( $signal_name );
161 # Handle a signal, preventing the program from terminating.
163 $kernel->sig_handled();
164 # Post a signal through POE rather than through the underlying OS.
166 # This only works within the same process.
167 $kernel->signal( $session, $signal_name, @optional_args );
168 State (event handler) management methods:
170 # Remove an existing handler from the current Session.
172 $kernel->state( $event_name );
173 # Add a new inline handler, or replace an existing one.
175 $kernel->state( $event_name, $code_reference );
176 # Add a new object or package handler, or replace an existing
178 # one. The object method will be the same as the eventname.
179 $kernel->state( $event_name, $object_ref_or_package_name );
180 # Add a new object or package handler, or replace an existing
182 # one. The object method may be different from the event name.
183 $kernel->state( $event_name, $object_ref_or_package_name, $method_name );
184 External reference count methods:
186 # Increment a session's external reference count.
188 $kernel->refcount_increment( $session_id, $refcount_name );
189 # Decrement a session's external reference count.
191 $kernel->refcount_decrement( $session_id, $refcount_name );
192 Kernel data accessors:
194 # Return a reference to the currently active session, or to the
196 # kernel if called outside any session.
197 $session = $kernel->get_active_session();
198 # Return the currently active event name, or an empty string if
200 # called outside any event.
201 $event = $kernel->get_active_event();
202 Exported symbols:
204 # A reference to the global POE::Kernel instance.
206 $poe_kernel
207 # Some graphical toolkits (Tk) require at least one active widget in
209 # order to use their event loops. POE allocates a main window so it
210 # can function when using one of these toolkits.
211 $poe_main_window
212
214 POE::Kernel is an event application kernel. It provides a lightweight,
215 cooperatively-timesliced process model in addition to the usual basic
216 event loop functions.
217 POE::Kernel cooperates with three external event loops. This is dis‐
219 cussed after the public methods are described.
220 The POE manpage describes a shortcut for using several POE modules at
222 once. It also includes a complete sample program with a brief walk‐
223 through of its parts.
224
226 This section discusses in more detail the POE::Kernel methods that
227 appear in the SYNOPSIS.
228 Kernel Management and Data Accessors
230 These functions manipulate the Kernel itself or retrieve information
232 from it.
233 ID
235 ID() returns the kernel's unique identifier.
236 print "The currently running Kernel is: $kernel->ID\n";
238 Every POE::Kernel instance is assigned an ID at birth. This ID tries
240 to differentiate any given instance from all the others, even if they
241 exist on the same machine. The ID is a hash of the machine's name
242 and the kernel's instantiation time and process ID.
243 ~/perl/poe$ perl -wl -MPOE -e 'print $poe_kernel->ID'
245 rocco.homenet-39240c97000001d8
246 run
248 run() starts the kernel's event loop. It returns only after every
249 session has stopped, or immediately if no sessions have yet been
250 started.
251 #!/usr/bin/perl -w
253 use strict;
254 use POE;
255 # ... start bootstrap session(s) ...
257 $poe_kernel->run();
259 exit;
260 The run() method may be called on an instance of POE::Kernel.
262 my $kernel = POE::Kernel->new();
264 $kernel->run();
265 It may also be called as class method.
267 POE::Kernel->run();
269 The run() method does not return a meaningful value.
271 run_one_timeslice
273 run_one_timeslice() checks for new events, which are enqueued, then
274 dispatches any events that were due at the time it was called. Then
275 it returns.
276 It is often used to emulate blocking behavior for procedural code.
278 my $done = 0;
280 sub handle_some_event {
282 $done = 1;
283 }
284 while (not $done) {
286 $kernel->run_one_timeslice();
287 }
288 Note: The above example will "spin" if POE::Kernel is done but $done
290 isn't set.
291 stop
293 stop() forcibly stops the kernel. The event queue is emptied, all
294 resources are released, and all sessions are deallocated. POE::Ker‐
295 nel's run() method returns as if everything ended normally, which is
296 a lie.
297 This function has a couple serious caveats. Use it with caution.
299 The session running when stop() is called will not fully destruct
301 until it returns. If you think about it, there's at least a refer‐
302 ence to the session in its call stack, plus POE::Kernel is holding
303 onto at least one reference so it can invoke the session.
304 Sessions are not notified about their destruction. If anything
306 relies on _stop being delivered, it will break and/or leak memory.
307 stop() has been added as an experimental function to support forking
309 child kernels with POE::Wheel::Run. We may remove it without notice
310 if it becomes really icky. If you have good uses for it, please men‐
311 tion them on POE's mailing list.
312 FIFO Event Methods
314 FIFO events are dispatched in the order in which they were queued.
316 These methods queue new FIFO events. A session will not spontaneously
317 stop as long as it has at least one FIFO event in the queue.
318 post SESSION, EVENT_NAME, PARAMETER_LIST
320 post SESSION, EVENT_NAME
321 post() enqueues an event to be dispatched to EVENT_NAME in SESSION.
322 If a PARAMETER_LIST is included, its values will be passed as argu‐
323 ments to EVENT_NAME's handler.
324 $_[KERNEL]->post( $session, 'do_this' );
326 $_[KERNEL]->post( $session, 'do_that', $with_this, $and_this );
327 $_[KERNEL]->post( $session, 'do_that', @with_these );
328 POE::Session->create(
330 inline_states => {
331 do_this => sub { print "do_this called with $_[ARG0] and $_[ARG1]\n" },
332 do_that => sub { print "do_that called with @_[ARG0..$#_]\n" },
333 }
334 );
335 The post() method returns a boolean value indicating whether the
337 event was enqueued successfully. $! will explain why the post()
338 failed:
339 ESRCH: The SESSION did not exist at the time of the post() call.
341 Posted events keep both the sending and receiving session alive until
343 they're dispatched.
344 yield EVENT_NAME, PARAMETER_LIST
346 yield EVENT_NAME
347 yield() enqueues an EVENT_NAME event for the session that calls it.
348 If a PARAMETER_LIST is included, its values will be passed as argu‐
349 ments to EVENT_NAME's handler.
350 yield() is shorthand for post() where the event's destination is the
352 current session.
353 Events posted with yield() must propagate through POE's FIFO before
355 they're dispatched. This effectively yields timeslices to other ses‐
356 sions which have events enqueued before it.
357 $kernel->yield( 'do_this' );
359 $kernel->yield( 'do_that', @with_these );
360 The previous yield() calls are equivalent to these post() calls.
362 $kernel->post( $session, 'do_this' );
364 $kernel->post( $session, 'do_that', @with_these );
365 The yield() method does not return a meaningful value.
367 Synchronous Events
369 Sometimes it's necessary to invoke an event handler right away, for
371 example to handle a time-critical external event that would be spoiled
372 by the time an event propagated through POE's FIFO. The kernel's
373 call() method provides for time-critical events.
374 call SESSION, EVENT_NAME, PARAMETER_LIST
376 call SESSION, EVENT_NAME
377 call() bypasses the FIFO to call EVENT_NAME in a SESSION, optionally
378 with values from a PARAMETER_LIST. The values will be passed as
379 arguments to EVENT_NAME at dispatch time.
380 call() returns whatever EVENT_NAME's handler does. The call() call's
382 status is returned in $!, which is 0 for success or a nonzero reason
383 for failure.
384 $return_value = $kernel->call( $session, 'do_this_now' );
386 die "could not do_this_now: $!" if $!;
387 POE uses call() to dispatch some resource events without FIFO
389 latency. Filehandle watchers, for example, would continue noticing a
390 handle's readiness until it was serviced by a handler. This could
391 result in several redundant readiness events being enqueued before
392 the first one was dispatched.
393 Reasons why call() might fail:
395 ESRCH: The SESSION did not exist at the time call() was called.
397 Delayed Events (Original Interface)
399 POE also manages timed events. These are events that should be dis‐
401 patched after at a certain time or after some time has elapsed. A ses‐
402 sion will not spontaneously stop as long as it has at least one pending
403 timed event. Alarms and delays always are enqueued for the current
404 session, so a SESSION parameter is not needed.
405 The kernel manages two types of timed event. Alarms are set to be dis‐
407 patched at a particular time, and delays are set to go off after a cer‐
408 tain interval.
409 If Time::HiRes is installed, POE::Kernel will use it to increase the
411 accuracy of timed events. The kernel will use the less accurate built-
412 in time() if Time::HiRes isn't available.
413 If the use of Time::HiRes is not desired, for whatever reason, it can
415 be disabled like so:
416 sub POE::Kernel::USE_TIME_HIRES () { 0 }
418 use POE;
419 alarm EVENT_NAME, EPOCH_TIME, PARAMETER_LIST
421 alarm EVENT_NAME, EPOCH_TIME
422 alarm EVENT_NAME
423 POE::Kernel's alarm() is a single-shot alarm. It first clears all
424 the timed events destined for EVENT_NAME in the current session. It
425 then may set a new alarm for EVENT_NAME if EPOCH_TIME is included,
426 optionally including values from a PARAMETER_LIST.
427 It is possible to post an alarm with an EPOCH_TIME in the past; in
429 that case, it will be placed towards the front of the event queue.
430 To clear existing timed events for 'do_this' and set a new alarm with
432 parameters:
433 $kernel->alarm( 'do_this', $at_this_time, @with_these_parameters );
435 Clear existing timed events for 'do_that' and set a new alarm without
437 parameters:
438 $kernel->alarm( 'do_that', $at_this_time );
440 To clear existing timed events for 'do_the_other_thing' without set‐
442 ting a new delay:
443 $kernel->alarm( 'do_the_other_thing' );
445 This method will clear all types of alarms without regard to how they
447 were set.
448 POE::Kernel's alarm() returns 0 on success or EINVAL if EVENT_NAME is
450 not defined.
451 alarm_add EVENT_NAME, EPOCH_TIME, PARAMETER_LIST
453 alarm_add EVENT_NAME, EPOCH_TIME
454 alarm_add() sets an additional timed event for EVENT_NAME in the cur‐
455 rent session without clearing pending timed events. The new alarm
456 event will be dispatched no earlier than EPOCH_TIME.
457 To enqueue additional alarms for 'do_this':
459 $kernel->alarm_add( 'do_this', $at_this_time, @with_these_parameters );
461 $kernel->alarm_add( 'do_this', $at_this_time );
462 Additional alarms can be cleared with POE::Kernel's alarm() method.
464 alarm_add() returns 0 on success or EINVAL if EVENT_NAME or
466 EPOCH_TIME is undefined.
467 delay EVENT_NAME, SECONDS, PARAMETER_LIST
469 delay EVENT_NAME, SECONDS
470 delay EVENT_NAME
471 delay() is a single-shot delayed event. It first clears all the
472 timed events destined for EVENT_NAME in the current session. If SEC‐
473 ONDS is included, it will set a new delay for EVENT_NAME to be dis‐
474 patched SECONDS seconds hence, optionally including values from a
475 PARAMETER_LIST. Please note that delay()ed event are placed on the
476 queue and are thus asynchronous.
477 delay() uses whichever time(2) is available within POE::Kernel. That
479 may be the more accurate Time::HiRes::time(), or perhaps not.
480 Regardless, delay() will do the right thing without sessions testing
481 for Time::HiRes themselves.
482 It's possible to post delays with negative SECONDS; in those cases,
484 they will be placed towards the front of the event queue.
485 To clear existing timed events for 'do_this' and set a new delay with
487 parameters:
488 $kernel->delay( 'do_this', $after_this_much_time, @with_these );
490 Clear existing timed events for 'do_that' and set a new delay without
492 parameters:
493 $kernel->delay( 'do_this', $after_this_much_time );
495 To clear existing timed events for 'do_the_other_thing' without set‐
497 ting a new delay:
498 $kernel->delay( 'do_the_other_thing' );
500 "delay()" returns 0 on success or a reason for its failure: EINVAL if
502 EVENT_NAME is undefined.
503 delay_add EVENT_NAME, SECONDS, PARAMETER_LIST
505 delay_add EVENT_NAME, SECONDS
506 delay_add() sets an additional delay for EVENT_NAME in the current
507 session without clearing pending timed events. The new delay will be
508 dispatched no sooner than SECONDS seconds hence.
509 To enqueue additional delays for 'do_this':
511 $kernel->delay_add( 'do_this', $after_this_much_time, @with_these );
513 $kernel->delay_add( 'do_this', $after_this_much_time );
514 Additional alarms can be cleared with POE::Kernel's delay() method.
516 delay_add() returns 0 on success or a reason for failure: EINVAL if
518 EVENT_NAME or SECONDS is undefined.
519 Delayed Events (June 2001 Interface)
521 These functions were finally added in June of 2001. They manage alarms
523 and delays by unique IDs, allowing existing alarms to be moved around,
524 added, and removed with greater accuracy than the original interface.
525 The June 2001 interface provides a different set of functions for
527 alarms, but their underlying semantics are the same. Foremost, they
528 are always set for the current session. That's why they don't require
529 a SESSION parameter.
530 For more information, see the previous section about the older alarms
532 interface.
533 alarm_set EVENT_NAME, TIME, PARAMETER_LIST
535 alarm_set EVENT_NAME, TIME
536 Sets an alarm. This differs from POE::Kernel's alarm() in that it
537 lets programs set alarms without clearing them. Furthermore, it
538 returns an alarm ID which can be used in other new-style alarm func‐
539 tions.
540 $alarm_id = $kernel->alarm_set( party => 1000000000 )
542 $kernel->alarm_remove( $alarm_id );
543 alarm_set sets $! and returns false if it fails. $! will be EINVAL
545 if one of the function's parameters is bogus.
546 See: alarm_remove,
548 alarm_adjust ALARM_ID, DELTA
550 alarm_adjust adjusts an existing alarm by a number of seconds, the
551 DELTA, which may be positive or negative. On success, it returns the
552 new absolute alarm time.
553 # Move the alarm 10 seconds back in time.
555 $new_time = $kernel->alarm_adjust( $alarm_id, -10 );
556 On failure, it returns false and sets $! to a reason for the failure.
558 That may be EINVAL if the alarm ID or the delta are bad values. It
559 could also be ESRCH if the alarm doesn't exist (perhaps it already
560 was dispatched). $! may also contain EPERM if the alarm doesn't
561 belong to the session trying to adjust it.
562 alarm_remove ALARM_ID
564 Removes an alarm from the current session, but first you must know
565 its ID. The ID comes from a previous alarm_set() call, or you could
566 hunt at random for alarms to remove.
567 Upon success, alarm_remove() returns something true based on its con‐
569 text. In a list context, it returns three things: The removed
570 alarm's event name, its scheduled time, and a reference to the list
571 of parameters that were included with it. This is all you need to
572 re-schedule the alarm later.
573 my @old_alarm_list = $kernel->alarm_remove( $alarm_id );
575 if (@old_alarm_list) {
576 print "Old alarm event name: $old_alarm_list[0]\n";
577 print "Old alarm time : $old_alarm_list[1]\n";
578 print "Old alarm parameters: @{$old_alarm_list[2]}\n";
579 }
580 else {
581 print "Could not remove alarm $alarm_id: $!\n";
582 }
583 In a scalar context, it returns a reference to a list of the three
585 things above.
586 my $old_alarm_scalar = $kernel->alarm_remove( $alarm_id );
588 if ($old_alarm_scalar) {
589 print "Old alarm event name: $old_alarm_scalar->[0]\n";
590 print "Old alarm time : $old_alarm_scalar->[1]\n";
591 print "Old alarm parameters: @{$old_alarm_scalar->[2]}\n";
592 }
593 else {
594 print "Could not remove alarm $alarm_id: $!\n";
595 }
596 Upon failure, it returns false and sets $! to the reason it failed.
598 $! may be EINVAL if the alarm ID is undefined, or it could be ESRCH
599 if no alarm was found by that ID. It may also be EPERM if some other
600 session owns that alarm.
601 alarm_remove_all
603 alarm_remove_all() removes all alarms from the current session. It
604 obviates the need for queue_peek_alarms(), which has been deprecated.
605 This function takes no arguments. In scalar context, it returns a
607 reference to a list of alarms that were removed. In list context, it
608 returns the list of removed alarms themselves.
609 Each removed alarm follows the same format as in alarm_remove().
611 my @removed_alarms = $kernel->alarm_remove_all( );
613 foreach my $alarm (@removed_alarms) {
614 print "-----\n";
615 print "Removed alarm event name: $alarm->[0]\n";
616 print "Removed alarm time : $alarm->[1]\n";
617 print "Removed alarm parameters: @{$alarm->[2]}\n";
618 }
619 my $removed_alarms = $kernel->alarm_remove_all( );
621 foreach my $alarm (@$removed_alarms) {
622 ...;
623 }
624 delay_set EVENT_NAME, SECONDS, PARAMETER_LIST
626 delay_set EVENT_NAME, SECONDS
627 delay_set() is a handy way to set alarms for a number of seconds
628 hence. Its EVENT_NAME and PARAMETER_LIST are the same as for
629 alarm_set, and it returns the same things as alarm_set, both as a
630 result of success and of failure.
631 It's only difference is that SECONDS is added to the current time to
633 get the time the delay will be dispatched. It uses whichever time()
634 POE::Kernel does, which may be Time::HiRes' high-resolution timer, if
635 that's available.
636 delay_adjust DELAY_ID, SECONDS
638 delay_adjust adjusts an existing delay to be a number of seconds in
639 the future. It is useful for refreshing watchdog timers, for
640 instance.
641 # Refresh a delay for 10 seconds into the future.
643 $new_time = $kernel->delay_adjust( $delay_id, 10 );
644 On failure, it returns false and sets $! to a reason for the failure.
646 That may be EINVAL if the delay ID or the seconds are bad values. It
647 could also be ESRCH if the delay doesn't exist (perhaps it already
648 was dispatched). $! may also contain EPERM if the delay doesn't
649 belong to the session trying to adjust it.
650 Numeric Session IDs and Symbolic Session Names (Aliases)
652 Every session is given a unique ID at birth. This ID combined with the
654 kernel's own ID can uniquely identify a particular session anywhere in
655 the world.
656 Sessions can also use the kernel's alias dictionary to give themselves
658 symbolic names. Once a session has a name, it may be referred to by
659 that name wherever a kernel method expects a session reference or ID.
660 Sessions with aliases are treated as daemons within the current pro‐
662 gram. They are kept alive even without other things to do. It's
663 assumed that they will receive events from some other session.
664 Aliases are passive work. A session with just an alias to keep it
666 alive can't do anything if there isn't some other active session around
667 to send it messages. POE knows this, and it will gladly kill off
668 aliased sessions if everything has become idle. This prevents "zombie"
669 sessions from keeping an otherwise dead program running.
670 alias_set ALIAS
672 alias_set() sets an ALIAS for the current session. The ALIAS may
673 then be used nearly everywhere a session reference or ID is expected.
674 Sessions may have more than one alias, and each must be defined in a
675 separate alias_set() call.
676 $kernel->alias_set( 'ishmael' ); # o/` A name I call myself. o/`
678 Aliases allow sessions to stay alive even when they may have nothing
680 to do. Sessions can use them to become autonomous services that
681 other sessions refer to by name.
682 Aliases keep sessions alive as long as the program has work to do.
684 If a program's remaining sessions are being kept alive solely by
685 aliases, they will be terminated. This prevents running, the remain‐
686 ing sessions will be terminated. This prevents deadlocks where two
687 or more sessions are idly waiting for events from each other.
688 $kernel->alias_set( 'httpd' );
690 $kernel->post( httpd => set_handler => $uri_regexp => 'callback_event' );
691 alias_set() returns 0 on success, or a nonzero failure indicator:
693 EEXIST
695 The alias already is assigned to a different session.
696 alias_remove ALIAS
698 alias_remove() clears an existing ALIAS from the current session.
699 The ALIAS will no longer refer to this session, and some other ses‐
700 sion may claim it.
701 $kernel->alias_remove( 'Shirley' ); # And don't call me Shirley.
703 If a session is only being kept alive by its aliases, it will stop
705 once they are removed.
706 alias_remove() returns 0 on success or a reason for its failure:
708 ESRCH: The Kernel's dictionary does not include the ALIAS being
710 removed.
711 EPERM: ALIAS belongs to some other session, and the current one does
713 not have the authority to clear it.
714 alias_resolve ALIAS
716 alias_resolve() returns a session reference corresponding to its
717 given ALIAS. This method has been overloaded over time, and now
718 ALIAS may be several things:
719 An alias:
721 $session_reference = $kernel->alias_resolve( 'irc_component' );
723 A stringified session reference. This is a form of weak reference:
725 $blessed_session_reference = $kernel->alias_resolve( "$stringified_one" );
727 A numeric session ID:
729 $session_reference = $kernel->alias_resolve( $session_id );
731 alias_resolve() returns undef upon failure, setting $! to explain the
733 error:
734 ESRCH: The Kernel's dictionary does not include ALIAS.
736 These functions work directly with session IDs. They are faster than
738 alias_resolve() in the specific cases where they're useful.
739 ID_id_to_session SESSION_ID
741 ID_id_to_session() returns a session reference for a given numeric
742 session ID.
743 $session_reference = ID_id_to_session( $session_id );
745 It returns undef if a lookup fails, and it sets $! to explain why the
747 lookup failed:
748 ESRCH: The session ID does not refer to a running session.
750 alias_list SESSION
752 alias_list
753 alias_list() returns a list of alias(es) associated with a SESSION,
754 or with the current session if a SESSION is omitted.
755 SESSION may be a session reference (either blessed or stringified), a
757 session ID, or a session alias. It will be resolved into a session
758 reference internally, and that will be used to locate the session's
759 aliases.
760 alias_list() returns a list of aliases associated with the session.
762 It returns an empty list if none were found.
763 ID_session_to_id SESSION_REFERENCE
765 ID_session_to_id() returns the ID associated with a session refer‐
766 ence. This is virtually identical to SESSION_REFERENCE->ID, except
767 that SESSION_REFERENCE may have been stringified. For example, this
768 will work, provided that the session exists:
769 $session_id = ID_session_to_id( "$session_reference" );
771 ID_session_to_id() returns undef if a lookup fails, and it sets $! to
773 explain why the lookup failed.
774 ESRCH: The session reference does not describe a session which is
776 currently running.
777 Filehandle Watcher Methods (Selects)
779 Filehandle watchers emit events when files become available to be read
781 from or written to. As of POE 0.1702 these events are queued along
782 with all the rest. They are no longer "synchronous" or "immediate".
783 Filehandle watchers are often called "selects" in POE because they were
785 originally implemented with the select(2) I/O multiplexing function.
786 File I/O event handlers are expected to interact with filehandles in a
788 way that causes them to stop being ready. For example, a select_read()
789 event handler should try to read as much data from a filehandle as it
790 can. The filehandle will stop being ready for reading only when all
791 its data has been read out.
792 Select events include two parameters.
794 "ARG0" holds the handle of the file that is ready.
796 "ARG1" contains 0, 1, or 2 to indicate whether the filehandle is ready
798 for reading, writing, or out-of-band reading (otherwise knows as "expe‐
799 dited" or "exception").
800 "ARG2..$#_" contain optional additional parameters passed to POE::Ker‐
802 nel's various I/O watcher methods.
803 "ARG0" and the other event handler parameter constants is covered in
805 POE::Session.
806 Sessions will not stop if they have active filehandle watchers.
808 select_read FILE_HANDLE, EVENT_NAME, ADDITIONAL_PARAMETERS
810 select_read FILE_HANDLE, EVENT_NAME
811 select_read FILE_HANDLE
812 select_read() starts or stops the kernel from watching to see if a
813 filehandle can be read from. An EVENT_NAME event will be enqueued
814 whenever the filehandle has data to be read. The optional ADDI‐
815 TIONAL_PARAMETERS will be passed to the input callback after the
816 usual I/O parameters.
817 # Emit 'do_a_read' event whenever $filehandle has data to be read.
819 $kernel->select_read( $filehandle, 'do_a_read' );
820 # Stop watching for data to be read from $filehandle.
822 $kernel->select_read( $filehandle );
823 select_read() does not return a meaningful value.
825 select_write FILE_HANDLE, EVENT_NAME
827 select_write FILE_HANDLE
828 select_write() starts or stops the kernel from watching to see if a
829 filehandle can be written to. An EVENT_NAME event will be enqueued
830 whenever it is possible to write data to the filehandle. The
831 optional ADDITIONAL_PARAMETERS will be passed to the input callback
832 after the usual I/O parameters.
833 # Emit 'flush_data' whenever $filehandle can be written to.
835 $kernel->select_writ( $filehandle, 'flush_data' );
836 # Stop watching for opportunities to write to $filehandle.
838 $kernel->select_write( $filehandle );
839 select_write() does not return a meaningful value.
841 select_expedite FILE_HANDLE, EVENT_NAME
843 select_expedite FILE_HANDLE
844 select_expedite() starts or stops the kernel from watching to see if
845 a filehandle can be read from "out-of-band". This is most useful for
846 datagram sockets where an out-of-band condition is meaningful. In
847 most cases it can be ignored. An EVENT_NAME event will be enqueued
848 whenever the filehandle can be read from out-of-band. The optional
849 ADDITIONAL_PARAMETERS will be passed to the input callback after the
850 usual I/O parameters.
851 Out of band data is called "expedited" because it's often available
853 ahead of a file or socket's normal data. It's also used in socket
854 operations such as connect() to signal an exception.
855 # Emit 'do_an_oob_read' whenever $filehandle has OOB data to be read.
857 $kernel->select_expedite( $filehandle, 'do_an_oob_read' );
858 # Stop watching for OOB data on the $filehandle.
860 $kernel->select_expedite( $filehandle );
861 select_expedite() does not return a meaningful value.
863 select_pause_read FILE_HANDLE
865 select_resume_read FILE_HANDLE
866 select_pause_write FILE_HANDLE
867 select_resume_write FILE_HANDLE
868 select_pause_read() and select_pause_write() temporarily pause events
869 that are generated when a FILE_HANDLE can be read from or written to,
870 respectively.
871 select_resume_read() and select_resume_write() turn events back on.
873 These functions are more efficient than select_read() and
875 select_write() because they don't perform full resource management
876 within POE::Kernel.
877 Pause and resume a filehandle's readable events:
879 $kernel->select_pause_read( $filehandle );
881 $kernel->select_resume_read( $filehandle );
882 Pause and resume a filehandle's writable events:
884 $kernel->select_pause_write( $filehandle );
886 $kernel->select_resume_write( $filehandle );
887 These methods don't return meaningful values.
889 select FILE_HANDLE, READ_EVENT, WRITE_EVENT, EXPEDITE_EVENT, ARGS
891 select FILE_HANDLE, READ_EVENT, WRITE_EVENT, EXPEDITE_EVENT
892 POE::Kernel's select() method alters a filehandle's read, write, and
893 expedite selects at the same time. It's one method call more expen‐
894 sive than doing the same thing manually, but it's more convenient to
895 code.
896 Defined event names set or change the events that will be emitted
898 when the filehandle becomes ready. Undefined names clear those
899 aspects of the watcher, stopping it from generating those types of
900 events.
901 This sets all three types of events at once.
903 $kernel->select( $filehandle, 'do_read', 'do_flush', 'do_read_oob' );
905 This clears all three types of events at once. If this filehandle is
907 the only thing keeping a session alive, then clearing its selects
908 will stop the session.
909 $kernel->select( $filehandle );
911 This sets up a filehandle for read-only operation.
913 $kernel->select( $filehandle, 'do_read', undef, 'do_read_oob' );
915 This sets up a filehandle for write-only operation.
917 $kernel->select( $filehandle, undef, 'do_flush' );
919 This method does not return a meaningful value.
921 Signal Watcher Methods
923 First some general notes about signal events and handling them.
925 Sessions only receive signal events that have been registered with
927 "sig()". In the past, they also would receive "_signal" events, but
928 this is no longer the case.
929 Child sessions are the ones created by another session. Signals are
931 dispatched to children before their parents. By the time a parent
932 receives a signal, all its children have already had a chance to handle
933 it.
934 The Kernel acts as the parent of every session. Signaling it causes
936 every interested session to receive the signal. This is how operating
937 system signals are implemented.
938 It is possible to post signals in POE that don't exist in the operating
940 system. They are placed into the queue as if they came from the oper‐
941 ating system, but they are not limited to signals recognized by kill().
942 POE uses a few of these "fictitious" signals to notify programs about
943 certain global events.
944 It is also possible to post signals to particular sessions. In those
946 cases, POE only calls the handlers for that session and its children.
947 Some signals are considered terminal. They will terminate the sessions
949 they touch if they are not marked as "handled". A signal is considered
950 handled (or not) for all the sessions it touches. Therefore, one ses‐
951 sion can handle a signal for the entire program. All the other ses‐
952 sions will still receive notice of the signal, but none of them will be
953 terminated if it's handled by the time it's fully dispatched.
954 The sig_handled() method is used to mark signals as handled.
956 POE also recognizes "non-maskable" signals. These will terminate a
958 program even when they are handled. For example, POE sends a non-mask‐
959 able UIDESTROY signal to indicate when the program's user interface has
960 been shut down.
961 Signal handling in older versions of Perl is not safe by itself. POE
963 is written to avoid as many signal problems as it can, but they still
964 may occur. SIGCHLD is a special exception: POE polls for child process
965 exits using waitpid() instead of a signal handler. Spawning child pro‐
966 cesses should be completely safe.
967 Here is a summary of the three signal levels.
969 benign
971 Benign signals just notify sessions that signals have been received.
972 They have no side effects if they are not handled.
973 terminal
975 Terminal signal may stop a program if they go unhandled. If any
976 event handler calls "sig_handled()", however, then the program will
977 continue to live.
978 The terminal system signals are: HUP, INT, KILL, QUIT and TERM.
980 There are two terminal fictitious signals, IDLE and DIE. IDLE is used
981 to notify leftover sessions when a program has run out of things to
982 do. DIE is used to notify sessions that an exception has occurred.
983 POE's automatic exception handling can be turned off by setting the
985 "CATCH_EXCEPTIONS" constant subroutine in "POE::Kernel" to 0 like so:
986 sub POE::Kernel::CATCH_EXCEPTIONS () { 0 }
988 nonmaskable
990 Nonmaskable signals are similar to terminal signals, but they stop a
991 program regardless whether it has been handled. POE implements two
992 nonmaskable signals, both of which are fictitious.
993 ZOMBIE is fired if the terminal signal IDLE did not wake anything up.
995 It is used to stop the remaining "zombie" sessions so that an inac‐
996 tive program will exit cleanly.
997 UIDESTROY is fired when a main or top-level user interface widget has
999 been destroyed. It is used to shut down programs when their inter‐
1000 faces have been closed.
1001 Some system signals are handled specially. These are SIGCHLD/SIGCLD,
1003 SIGPIPE, and SIGWINCH.
1004 SIGCHLD/SIGCLD Events
1006 SIGCHLD and SIGCLD both indicate that a child process has terminated.
1007 The signal name varies from one operating system to another.
1008 POE::Kernel always sends the program a CHLD signal, regardless of the
1009 operating system's name for it. This simplifies your code since you
1010 don't need to check for both.
1011 The SIGCHLD/SIGCLD signal event is delivered to handlers registered
1013 by both the sig() method and sig_child().
1014 The SIGCHLD/SIGCHLD signal event comes with three custom parameters.
1016 "ARG0" contains 'CHLD', even if SIGCLD was caught. "ARG1" contains
1018 the ID of the exiting child process. "ARG2" contains the return
1019 value from $?.
1020 SIGPIPE Events
1022 Normally, system signals are posted to the Kernel so they can propa‐
1023 gate to every session. SIGPIPE is an exception to this rule. It is
1024 posted to the session that is currently running. It still will prop‐
1025 agate through that session's children, but it will not go beyond that
1026 parent/child tree.
1027 SIGPIPE is mostly moot since POE will usually return an EPIPE error
1029 instead.
1030 SIGWINCH Events
1032 Window resizes can generate a large number of signals very quickly,
1033 and this can easily cause perl to dump core. This should not be a
1034 problem in newer versions of Perl (after 5.8.0) because they make
1035 signals safe for the world.
1036 The Event module also claims to handle signals safely. Its signal
1038 handlers are written in C++, and they can do more interesting things
1039 than plain Perl handlers.
1040 Finally, here are POE::Kernel's signal methods themselves.
1042 sig SIGNAL_NAME, EVENT_NAME
1044 sig SIGNAL_NAME
1045 sig() registers or unregisters a EVENT_NAME event for a particular
1046 SIGNAL_NAME. Signal names are the same as %SIG uses, with one excep‐
1047 tion: CLD is always delivered as CHLD, so handling CHLD will always
1048 do the right thing.
1049 $kernel->sig( INT => 'event_sigint' );
1051 To unregister a signal handler, just leave off the event it should
1053 generate, or pass it in undefined.
1054 $kernel->sig( 'INT' );
1056 $kernel->sig( INT => undef );
1057 It's possible to register events for signals that the operating sys‐
1059 tem will never generate. These "fictitious" signals can however be
1060 generated through POE's signal() method instead of kill(2).
1061 The sig() method does not return a meaningful value.
1063 sig_child PID, EVENT_NAME
1065 sig_child PID
1066 sig_chld() is a convenient way to deliver an event (EVENT_NAME) with
1067 some OPTIONAL_ARGS only when a child process specified by PID has
1068 been reaped. Omit EVENT_NAME and OPTIONAL_ARGS to stop waiting for a
1069 given PID.
1070 sig_child() differs from using sig() to handle CHLD:
1072 sig_child() notifies a session when a particular process ID has been
1074 reaped. sig(CHLD, EVENT) notifies a session for every SIGCHLD deliv‐
1075 ered regardless of the PID.
1076 sig_child() keeps a session alive until the given PID has been
1078 reaped. The watcher is automatically removed when the event for the
1079 given process ID has been delivered. sig() does not keep a session
1080 alive.
1081 sig_handled
1083 sig_handled() informs POE that a signal was handled. It is only
1084 meaningful within event handlers that are triggered by signals.
1085 signal SESSION, SIGNAL_NAME, OPTIONAL_ARGS
1087 signal SESSION, SIGNAL_NAME
1088 signal() posts a signal event to a particular session (and its chil‐
1089 dren) through POE::Kernel rather than actually signaling the process
1090 through the operating system. Because it injects signal events
1091 directly into POE's Kernel, its SIGNAL_NAME doesn't have to be one
1092 the operating system understands.
1093 For example, this posts a fictitious signal to some session:
1095 $kernel->signal( $session, 'DIEDIEDIE' );
1097 POE::Kernel's signal() method doesn't return a meaningful value.
1099 signal_ui_destroy WIDGET
1101 This registers a widget with POE::Kernel such that the Kernel fires a
1102 UIDESTROY signal when the widget is closed or destroyed. The exact
1103 trigger depends on the graphical toolkit currently being used.
1104 # Fire a UIDESTROY signal when this top-level window is deleted.
1106 $heap->{gtk_toplevel_window} = Gtk::Window->new('toplevel');
1107 $kernel->signal_ui_destroy( $heap->{gtk_toplevel_window} );
1108 POE::Session also discusses signal events.
1110 Session Management Methods
1112 These methods manage sessions.
1114 detach_child SESSION
1116 Detaches SESSION from the current session. SESSION must be a child
1117 of the current session, or this call will fail. detach_child()
1118 returns 1 on success. If it fails, it returns false and sets $! to
1119 one of the following values:
1120 ESRCH indicates that SESSION is not a valid session.
1122 EPERM indicates that SESSION is not a child of the current session.
1124 This call may generate corresponding _parent and/or _child events.
1126 See PREDEFINED EVENT NAMES in POE::Session's manpage for more infor‐
1127 mation about _parent and _child events.
1128 detach_myself
1130 Detaches the current session from it parent. The parent session
1131 stops owning the current one. The current session is instead made a
1132 child of POE::Kernel. detach_child() returns 1 on success. If it
1133 fails, it returns 0 and sets $! to EPERM to indicate that the current
1134 session already is a child of POE::Kernel and cannot be detached from
1135 it.
1136 This call may generate corresponding _parent and/or _child events.
1138 See PREDEFINED EVENT NAMES in POE::Session's manpage for more infor‐
1139 mation about _parent and _child events.
1140 State Management Methods
1142 State management methods let sessions hot swap their event handlers.
1144 It would be rude to change another session's handlers, so these methods
1145 only affect the current one.
1146 state EVENT_NAME
1148 state EVENT_NAME, CODE_REFERENCE
1149 state EVENT_NAME, OBJECT_REFERENCE
1150 state EVENT_NAME, OBJECT_REFERENCE, OBJECT_METHOD_NAME
1151 state EVENT_NAME, PACKAGE_NAME
1152 state EVENT_NAME, PACKAGE_NAME, PACKAGE_METHOD_NAME
1153 Depending on how it's used, state() can add, remove, or update an
1154 event handler in the current session.
1155 The simplest form of state() call deletes a handler for an event.
1157 This example removes the current session's "do_this" handler.
1158 $kernel->state( 'do_this' );
1160 The next form assigns a coderef to an event. If the event is already
1162 being handled, its old handler will be discarded. Any events already
1163 in POE's queue will be dispatched to the new handler.
1164 Plain coderef handlers are also called "inline" handlers because they
1166 originally were defined with inline anonymous subs.
1167 $kernel->state( 'do_this', \&this_does_it );
1169 The third and fourth forms register or replace a handler with an
1171 object method. These handlers are called "object states" or object
1172 handlers. The third form maps an event to a method with the same
1173 name.
1174 $kernel->state( 'do_this', $with_this_object );
1176 The fourth form maps an event to a method with a different name.
1178 $kernel->state( 'do_this', $with_this_object, $calling_this_method );
1180 The fifth and sixth forms register or replace a handler with a pack‐
1182 age method. These handlers are called "package states" or package
1183 handlers. The fifth form maps an event to a function with the same
1184 name.
1185 $kernel->state( 'do_this', $with_this_package );
1187 The sixth form maps an event to a function with a different name.
1189 $kernel->state( 'do_this', $with_this_package, $calling_this_function );
1191 POE::Kernel's state() method returns 0 on success or a nonzero code
1193 explaining why it failed:
1194 ESRCH: The Kernel doesn't recognize the currently active session.
1196 This happens when state() is called when no session is active.
1197 External Reference Count Methods
1199 The Kernel internally maintains reference counts on sessions that have
1201 active resource watchers. The reference counts are used to ensure that
1202 a session doesn't self-destruct while it's doing something important.
1203 POE::Kernel's external reference counting methods let resource watcher
1205 developers manage their own reference counts. This lets the watchers
1206 keep their sessions alive when necessary.
1207 refcount_increment SESSION_ID, REFCOUNT_NAME
1209 refcount_decrement SESSION_ID, REFCOUNT_NAME
1210 refcount_increment() increments a session's external reference count,
1211 returning the reference count after the increment.
1212 refcount_decrement() decrements a session's external reference count,
1214 returning the reference count after the decrement.
1215 $new_count = $kernel->refcount_increment( $session_id, 'thingy' );
1217 $new_count = $kernel->refcount_decrement( $session_id, 'thingy' );
1218 Both methods return undef on failure and set $! to explain the fail‐
1220 ure.
1221 ESRCH: There is no session SESSION_ID currently active.
1223 Kernel Data Accessors
1225 The Kernel keeps some information which can be useful to other
1227 libraries. These functions provide a consistent, safe interface to the
1228 Kernel's internal data.
1229 get_active_session
1231 get_active_session() returns a reference to the session which is cur‐
1232 rently running. It returns a reference to the Kernel itself if no
1233 other session is running. This is one of the times where the Kernel
1234 pretends it's just another session.
1235 my $active_session = $poe_kernel->get_active_session();
1237 This is a convenient way for procedurally called libraries to get a
1239 reference to the current session. Otherwise a programmer would
1240 tediously need to include "SESSION" with every call.
1241 get_active_event
1243 get_active_event() returns the currently active event name or an
1244 empty string if called outside any event.
1245 get_event_count
1247 get_event_count() returns the number of pending events in the queue.
1248 WARNING: probably will be DEPRECATED in the future!
1250 get_next_event_time
1252 get_next_event_time() returns the priority of the next event ( look
1253 at POE::Queue for more information as it's actually
1254 $queue->get_next_priority )
1255 WARNING: probably will be DEPRECATED in the future!
1257 Kernel Internal Methods
1259 Those methods are primarily used by other POE modules and are not for
1261 public consumption.
1262 new
1264 Accepts no arguments and returns a singleton POE::Kernel instance.
1265 session_alloc
1267 Allocates a session in the Kernel - does not create it! Fires off the
1268 _start event with the arguments given.
1269
1271 POE::Kernel supports any number of event loops. Four are included in
1272 the base distribution, and others are available on the CPAN. POE's
1273 public interfaces remain the same regardless of the event loop being
1274 used.
1275 There are three ways to load an alternate event loop. The simplest is
1277 to load the event loop before loading POE::Kernel. Remember that POE
1278 loads POE::Kernel internally.
1279 use Gtk;
1281 use POE;
1282 POE::Kernel detects that Gtk has been loaded, and it loads the appro‐
1284 priate internal code to use it.
1285 You can also specify which loop to load directly. Event loop bridges
1287 are named "POE::Loop::$loop_module", where $loop_module is the name of
1288 the module, with "::" translated to underscores. For example:
1289 use POE qw( Loop::Event_Lib );
1291 would load POE::Loop::Event_Lib (which may or may not be on CPAN).
1293 If you'd rather use POE::Kernel directly, it has a different import
1295 syntax:
1296 use POE::Kernel { loop => "Tk" };
1298 The four event loops included in POE's distribution:
1300 POE's default select() loop. It is included so at least something will
1302 work on any given platform.
1303 Event.pm. This provides compatibility with other modules requiring
1305 Event's loop. It may also introduce safe signals in versions of Perl
1306 prior to 5.8, should you need them.
1307 Gtk and Tk event loops. These are included to support graphical tool‐
1309 kits. Others are on the CPAN, including Gtk2 and hopefully WxPerl
1310 soon. When using Tk with POE, POE supplies an already-created
1311 $poe_main_window variable to use for your main window. Calling Tk's
1312 MainWindow->new() often has an undesired outcome.
1313 IO::Poll. This is potentially more efficient than POE's default
1315 select() code in large scale clients and servers.
1316 Many external event loops expect plain coderefs as callbacks.
1318 POE::Session has postback() and callback() methods that create call‐
1319 backs suitable for external event loops. In turn, they post() or
1320 call() POE event handlers.
1321 Kernel's Debugging Features
1323 POE::Kernel contains a number of assertion and tracing flags. They
1325 were originally created to debug POE::Kernel itself, but they are also
1326 useful for tracking down other problems.
1327 Assertions are the quiet ones. They only create output when something
1329 catastrophic has happened. That output is almost always fatal. They
1330 are mainly used to check the sanity of POE's internal data structures.
1331 Traces are assertions' annoying cousins. They noisily report on the
1333 status of a running POE::Kernel instance, but they are never fatal.
1334 Assertions and traces incur performance penalties when enabled. It's
1336 probably a bad idea to enable them in live systems. They are all dis‐
1337 abled by default.
1338 Assertion and tracing flags can be defined before POE::Kernel is first
1340 used.
1341 # Turn on everything.
1343 sub POE::Kernel::ASSERT_DEFAULT () { 1 }
1344 sub POE::Kernel::TRACE_DEFAULT () { 1 }
1345 use POE; # Includes POE::Kernel
1346 It is also possible to enable them using shell environment variables.
1348 The environment variables follow the same names as the constants in
1349 this section, but "POE_" is prepended to them.
1350 POE_ASSERT_DEFAULT=1 POE_TRACE_DEFAULT=1 ./my_poe_program
1352 Assertions will be discussed first.
1354 ASSERT_DATA
1356 ASSERT_DATA enables a variety of runtime integrity checks within
1357 POE::Kernel and its event loop bridges. This can impose a signifi‐
1358 cant runtime penalty, so it is off by default. The test programs for
1359 POE all enable ASSERT_DEFAULT, which includes ASSERT_DATA.
1360 ASSERT_DEFAULT
1362 ASSERT_DEFAULT is used as the default value for all the other assert
1363 constants. Setting it true is a quick and reliable way to ensure all
1364 assertions are enabled.
1365 ASSERT_EVENTS
1367 ASSERT_EVENTS enables checks for dispatching events to nonexistent
1368 sessions.
1369 ASSERT_FILES
1371 ASSERT_FILES enables some runtime checks on the file multiplexing
1372 syscalls used to drive POE.
1373 ASSERT_RETVALS
1375 ASSERT_RETVALS causes POE::Kernel to die if a method would return an
1376 error. See also TRACE_RETVALS if you want a runtime warning rather
1377 than a hard error.
1378 ASSERT_USAGE
1380 ASSERT_USAGE enables runtime parameter checking in a lot of POE::Ker‐
1381 nel method calls. These are disabled by default because they impart
1382 a hefty performance penalty.
1383 Then there are the trace options.
1385 TRACE_DEFAULT
1387 TRACE_DEFAULT is used as the default value for all the other trace
1388 constants. Setting it true is a quick and reliable way to ensure all
1389 traces are enabled.
1390 TRACE_DESTROY
1392 Enable TRACE_DESTROY to receive a dump of the contents of Session
1393 heaps when they finally DESTROY. It is indispensable for finding
1394 memory leaks, which often hide in Session heaps.
1395 TRACE_EVENTS
1397 The music goes around and around, and it comes out here.
1398 TRACE_EVENTS enables messages that tell what happens to FIFO and
1399 alarm events: when they're queued, dispatched, or discarded, and what
1400 their handlers return.
1401 TRACE_FILENAME
1403 By default, trace messages go to STDERR. If you'd like them to go
1404 elsewhere, set TRACE_FILENAME to the file where they should go.
1405 TRACE_FILES
1407 TRACE_FILES enables or disables messages that tell how files are
1408 being processed within POE::Kernel and the event loop bridges.
1409 TRACE_STATISTICS
1411 This feature is experimental. No doubt it will change.
1412 TRACE_STATISTICS enables runtime gathering and reporting of various
1414 performance metrics within a POE program. Some statistics include
1415 how much time is spent processing event callbacks, time spent in
1416 POE's dispatcher, and the time spent waiting for an event. A report
1417 is displayed just before run() returns, and the data can be retrieved
1418 at any time using stat_getdata().
1419 stat_getdata() returns a hash of various statistics and their values
1421 The statistics are calculated using a sliding window and vary over
1422 time as a program runs.
1423 TRACE_PROFILE
1425 TRACE_PROFILE switches on event profiling. This causes the Kernel to
1426 keep a count of every event it dispatches. A report of the events
1427 and their frequencies is displayed just before run() returns, or at
1428 any time via stat_show_profile().
1429 TRACE_REFCNT
1431 TRACE_REFCNT displays messages about reference counts for sessions,
1432 including garbage collection tests (formerly TRACE_GARBAGE). This is
1433 perhaps the most useful debugging trace since it will explain why
1434 sessions do or don't die.
1435 TRACE_RETVALS
1437 TRACE_RETVALS enables carping whenever a Kernel method is about to
1438 return an error. See ASSERT_RETVALS if you would like the Kernel to
1439 be stricter than this.
1440 TRACE_SESSIONS
1442 TRACE_SESSIONS enables messages pertaining to session management.
1443 These messages include notice when sessions are created or destroyed.
1444 They also include parent and child relationship changes.
1445 TRACE_SIGNALS
1447 TRACE_SIGNALS enables or disables information about signals caught
1448 and dispatched within POE::Kernel.
1449
1451 POE::Kernel exports two symbols for your coding enjoyment: $poe_kernel
1452 and $poe_main_window. POE::Kernel is implicitly used by POE itself, so
1453 using POE gets you POE::Kernel (and its exports) for free.
1454 $poe_kernel
1456 $poe_kernel contains a reference to the process' POE::Kernel
1457 instance. It's mainly useful for getting at the kernel from places
1458 other than event handlers.
1459 For example, programs can't call the Kernel's run() method without a
1461 reference, and they normally don't get references to the Kernel with‐
1462 out being in a running event handler. This gets them going:
1463 $poe_kernel->run();
1465 It's also handy from within libraries, but event handlers themselves
1467 receive "KERNEL" parameters and don't need to use $poe_kernel
1468 directly.
1469 $poe_main_window
1471 Some graphical toolkits (currently only Tk) require at least one wid‐
1472 get be created before their event loops are usable. POE::Kernel
1473 allocates a main window in these cases, and exports a reference to
1474 that window in $poe_main_window. For all other toolkits, this
1475 exported variable is undefined.
1476 Programs are free to use $poe_main_window for whatever needs. They
1478 may even assign a widget to it when using toolkits that don't require
1479 an initial widget (Gtk for now).
1480 $poe_main_window is undefined if a graphical toolkit isn't used.
1482 See: signal_ui_destroy
1484
1486 The SEE ALSO section in POE contains a table of contents covering the
1487 entire POE distribution.
1488
1490 There is no mechanism in place to prevent external reference count
1491 names from clashing.
1492 Probably lots more.
1494
1496 Please see POE for more information about authors and contributors.
1497perl v5.8.8 2006-09-01 POE::Kernel(3)