Chip 2000 May

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _cce05157502fd5824070c75afb46deef < prev next >

Wrap

Text File | 2000-03-23 | 24KB | 512 lines

<HTML> <HEAD> <TITLE>POE::Kernel - POE Event Queue and Resource Manager</TITLE> <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> POE::Kernel - POE Event Queue and Resource Manager </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <LI><A HREF="#exported symbols">EXPORTED SYMBOLS</A></LI> <LI><A HREF="#public kernel methods">PUBLIC KERNEL METHODS</A></LI> <UL> <LI><A HREF="#kernel management methods">Kernel Management Methods</A></LI> <LI><A HREF="#session management methods">Session Management Methods</A></LI> <LI><A HREF="#event management methods">Event Management Methods</A></LI> <LI><A HREF="#alarm management methods">Alarm Management Methods</A></LI> <LI><A HREF="#alias management methods">Alias Management Methods</A></LI> <LI><A HREF="#select management methods">Select Management Methods</A></LI> <LI><A HREF="#signal management methods">Signal Management Methods</A></LI> <LI><A HREF="#process management methods">Process Management Methods</A></LI> <LI><A HREF="#state management methods">State Management Methods</A></LI> <LI><A HREF="#id management methods">ID Management Methods</A></LI> </UL> <LI><A HREF="#see also">SEE ALSO</A></LI> <LI><A HREF="#bugs">BUGS</A></LI> <LI><A HREF="#authors & copyrights">AUTHORS & COPYRIGHTS</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> POE::Kernel - POE Event Queue and Resource Manager <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> #!/usr/bin/perl -w use strict; use POE; # Includes POE::Kernel and POE::Session print $poe_kernel->ID(); # This process' unique ID. new POE::Session( ... ); # Bootstrap sessions are here. $poe_kernel->run(); # Run the kernel. exit; # Exit when the kernel's done.</PRE> <PRE> # Session management methods: $kernel->session_create( ... );</PRE> <PRE> # Event management methods: $kernel->post( $session, $state, @args ); $kernel->yield( $state, @args ); $kernel->call( $session, $state, @args );</PRE> <PRE> # Alarms and timers: $kernel->alarm( $state, $time, @args ); $kernel->delay( $state, $seconds, @args );</PRE> <PRE> # Aliases: $status = $kernel->alias_set( $alias ); $status = $kernel->alias_remove( $alias ); $session_reference = $kernel->alias_resolve( $alias );</PRE> <PRE> # Selects: $kernel->select( $file_handle, $read_state_name, # or undef to remove it $write_state_name, # or undef to remove it $expedite_state_same, # or undef to remove it ); $kernel->select_read( $file_handle, $read_state_name ); $kernel->select_write( $file_handle, $write_state_name ); $kernel->select_expedite( $file_handle, $expedite_state_name );</PRE> <PRE> # Signals: $kernel->sig( $signal_name, $state_name ); # Registers a handler. $kernel->signal( $session, $signal_name ); # Posts a signal.</PRE> <PRE> # Processes. $kernel->fork(); # "Safe" fork that polls for SIGCHLD.</PRE> <PRE> # States: $kernel->state( $state_name, $code_reference ); # Inline state $kernel->state( $method_name, $object_reference ); # Object state $kernel->state( $function_name, $package_name ); # Package state $kernel->state( $state_name, # Object or package $object_or_package_reference, # state, mapped to $object_or_package_method, # different method. );</PRE> <PRE> # IDs: $kernel->ID(); # Return the Kernel's unique ID. $kernel->ID_id_to_session($id); # Return undef, or the ID's session. $kernel->ID_session_to_id($session); # Return undef, or the session's ID.</PRE> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> POE::Kernel contains POE's event loop, select logic and resource management methods. There can only be one POE::Kernel per process, and it's created automatically the first time POE::Kernel is used. This simplifies signal delivery in the present and threads support in the future. <HR> <H1><A NAME="exported symbols">EXPORTED SYMBOLS</A></H1> POE::Kernel exports $poe_kernel, a reference to the program's single kernel instance. This mainly is used in the main package, so that $poe_kernel-><CODE>run()</CODE> may be called cleanly. Sessions' states should endeavor to use $_[KERNEL], since $poe_kernel may not be available, or it may be different than the kernel actually invoking the object. <HR> <H1><A NAME="public kernel methods">PUBLIC KERNEL METHODS</A></H1> POE::Kernel contains methods to manage the kernel itself, sessions, and resources such as files, signals and alarms. Many of the public Kernel methods generate events. Please see the ``PREDEFINED EVENTS AND PARAMETERS'' section in POE::Session's documentation. <H2><A NAME="kernel management methods">Kernel Management Methods</A></H2> <UL> <LI> POE::Kernel::run() POE::Kernel::run() starts the kernel's event loop. It will not return until all its sessions have stopped. There are two corollaries to this rule: It will return immediately if there are no sessions; and if sessions never exit, neither will run(). </UL> <H2><A NAME="session management methods">Session Management Methods</A></H2> <UL> <LI> POE::Kernel::session_create(...) POE::Kernel::session_create(...) creates a new session in the kernel. It is an alias for POE::Session::new(...), and it accepts the same parameters. Please see POE::Session::new(...) for more information. As of version 0.07, POE::Session is a proper object with public methods and everything. Therefore session_create is depreciated starting with version 0.07. </UL> <H2><A NAME="event management methods">Event Management Methods</A></H2> Events tell sessions which state to invoke next. States are defined when sessions are created. States may also be added, removed or changed at runtime by POE::Kernel::state(), which acts on the current session. There are a few ways to send events to sessions. Events can be posted, in which case the kernel queues them and dispatches them in FIFO order. States can also be called immediately, bypassing the queue. Immediate calls can be useful for ``critical sections''; for example, POE's I/O abstractions use <CODE>call()</CODE> to minimize event latency. To learn more about events and the information they convey, please see ``PREDEFINED EVENTS AND PARAMETERS'' in the POE::Session documentation. <UL> <LI> POE::Kernel::post( $destination, $state, @args ) POE::Kernel::post places an event in the kernel's queue. The kernel dispatches queued events in FIFO order. When posted events are dispatched, their corresponding states are invoked in a scalar context, and their return values are discarded. Signal handlers work differently, but they're not invoked as a result of post(). If a state's return value is important, there are at least two ways to get it. First, have the $destination post a return vent to its $_[SENDER]; second, use POE::Kernel::call() instead. POE::Kernel::post returns undef on failure, or an unspecified defined value on success. $! is set to the reason why the post failed. <LI> POE::Kernel::yield( $state, @args ) POE::Kernel::yield is an alias for posting an event to the current session. It does not immediately swap call stacks like <CODE>yield()</CODE> in real thread libraries might. If there's a way to do this in perl, I'd sure like to know. <LI> POE::Kernel::call( $session, $state, $args ) POE::Kernel::call immediately dispatches an event to a session. States invoked this way are evaluated in a scalar context, and <CODE>call()</CODE> returns their return values. <CODE>call()</CODE> can exercise bugs in perl and/or the C library (we're not really sure which just yet). This only seems to occur when one state (state1) is destroyed from another state (state0) as a result of state0 being called from state1. Until that bug is pinned down and fixed, if your program dumps core with a SIGSEGV, try changing your call()s to post()s. <CODE>call()</CODE> returns undef on failure. It may also return undef on success, if the called state returns success. What a mess. <CODE>call()</CODE> also sets $! to 0 on success, regardless of what it's set to in the called state. </UL> <H2><A NAME="alarm management methods">Alarm Management Methods</A></H2> Alarms are just events that are scheduled to be dispatched at some later time. POE's queue is a priority queue keyed on time, so these events go to the appropriate place in the queue. Posted events are really enqueued for ``now'' (defined as whatever <A HREF="../../../lib/Pod/perlfunc.html#item_time"><CODE>time()</CODE></A> returns). If Time::HiRes is available, POE will use it to achieve better resolution on enqueued events. <UL> <LI> POE::Kernel::alarm( $state, $time, @args ) The <A HREF="../../../lib/Pod/perlfunc.html#item_alarm"><CODE>alarm()</CODE></A> method enqueues an event with a future dispatch time, specified in seconds since whatever epoch <A HREF="../../../lib/Pod/perlfunc.html#item_time"><CODE>time()</CODE></A> uses (usually the UNIX epoch). If $time is in the past, it will be clipped to time(), making the <A HREF="../../../lib/Pod/perlfunc.html#item_alarm"><CODE>alarm()</CODE></A> call synonymous to <CODE>post()</CODE> but with some extra overhead. Alarms are keyed by state name. That is, there can be only one pending alarm for any given state. This is a design bug, and there are plans to fix it. It is possible to remove an alarm that hasn't yet been dispatched: <PRE> $kernel->alarm( $state ); # Removes the alarm for $state</PRE> Subsequent alarms set for the same name will overwrite previous ones. This is useful for timeout timers that must be continually refreshed. The <A HREF="../../../lib/Pod/perlfunc.html#item_alarm"><CODE>alarm()</CODE></A> method can be misused to remove events from the kernel's queue. This happens because alarms are merely events scheduled for a future time. This behavior is considered to be a bug, and there are plans to fix it. <LI> POE::Kernel::delay( $state, $seconds, @args ); The <CODE>delay()</CODE> method is an alias for: <PRE> $kernel->alarm( $state, time() + $seconds, @args );</PRE> However, because <A HREF="../../../lib/Pod/perlfunc.html#item_time"><CODE>time()</CODE></A> is called within the POE::Kernel package, it uses Time::HiRes if it's available. This saves programs from having to figure out if Time::HiRes is available themselves. All the details for POE::Kernel::alarm() apply to <CODE>delay()</CODE> as well. For example, delays may be removed by omitting the $seconds and @args parameters: <PRE> $kernel->delay( $state ); # Removes the delay for $state</PRE> And <CODE>delay()</CODE> can be misused to remove events from the kernel's queue. Please see POE::Kernel::alarm() for more information. </UL> <H2><A NAME="alias management methods">Alias Management Methods</A></H2> Aliases allow sessions to be referenced by name instead of by session reference. They also allow sessions to remain active without having selects or events. This provides support for ``daemon'' sessions that act as resources but don't necessarily have resources themselves. Aliases must be unique. Sessions may have more than one alias. <UL> <LI> POE::Kernel::alias_set( $alias ) The <CODE>alias_set()</CODE> method sets an alias for the current session. It returns 1 on success. On failure, it returns 0 and sets $! to one of: <PRE> EEXIST - The alias already exists for another session.</PRE> <LI> POE::Kernel::alias_remove( $alias ) The <CODE>alias_remove()</CODE> method removes an alias for the current session. It returns 1 on success. On failure, it returns 0 and sets $! to one of: <PRE> ESRCH - The alias does not exist. EPERM - The alias belongs to another session.</PRE> <LI> POE::Kernel::alias_resolve( $alias ) The <CODE>alias_resolve()</CODE> method returns a session reference corresponding to the given alias. POE::Kernel does this internally, so it's usually not necessary. It returns a session reference on success. On failure, it returns undef and sets $! to one of: <PRE> ESRCH - The alias does not exist.</PRE> </UL> <H2><A NAME="select management methods">Select Management Methods</A></H2> Selects are file handle monitors. They generate events to indicate when activity occurs on the file handles they watch. POE keeps track of how many selects are watching a file handle, and it will close the file when nobody is looking at it. There are three types of select. Each corresponds to one of the bit vectors in Perl's four-argument <A HREF="../../../lib/Pod/perlfunc.html#item_select"><CODE>select()</CODE></A> function. ``Read'' selects generate events when files become ready for reading. ``Write'' selects generate events when files are available to be written to. ``Expedite'' selects generate events when files have out-of-band information to be read. <UL> <LI> POE::Kernel::select( $filehandle, $rd_state, $wr_state, $ex_state ) The <A HREF="../../../lib/Pod/perlfunc.html#item_select"><CODE>select()</CODE></A> method manipulates all three selects for a file handle at the same time. Selects are added for each defined state, and selects are removed for undefined states. <LI> POE::Kernel::select_read( $filehandle, $read_state ) The <CODE>select_read()</CODE> method adds or removes a file handle's read select. It leaves the other two unchanged. <LI> POE::Kernel::select_write( $filehandle, $write_state ) The <CODE>select_write()</CODE> method adds or removes a file handle's write select. It leaves the other two unchanged. <LI> POE::Kernel::select_expedite( $filehandle, $expedite_state ) The <CODE>select_expedite()</CODE> method adds or removes a file handle's expedite select. It leaves the other two unchanged. </UL> <H2><A NAME="signal management methods">Signal Management Methods</A></H2> The POE::Session documentation has more information about _signal events. POE currently does not make Perl's signals safe. Using signals is okay in short-lived programs, but long-uptime servers may eventually dump core if they receive a lot of signals. POE provides a ``safe'' <A HREF="../../../lib/Pod/perlfunc.html#item_fork"><CODE>fork()</CODE></A> function that periodically reaps children without using signals; it emulates the system's SIGCHLD signal for each process in reaps. Mileage varies considerably. The kernel generates _signal events when it receives signals from the operating system. Sessions may also send signals between themselves without involving the OS. The kernel determines whether or not signals have been handled by looking at _signal states' return values. If the state returns logical true, then it means the signal was handled. If it returns false, then the kernel assumes the signal wasn't handled. POE will stop sessions that don't handle some signals. These ``terminal'' signals are QUIT, INT, KILL, TERM, HUP, and the fictitious IDLE signal. POE broadcasts SIGIDLE to all sessions when the kernel runs out of events to dispatch, and when there are no alarms or selects to generate new events. Finally, there is one fictitious signal that always stops a session: ZOMBIE. If the kernel remains idle after SIGIDLE is broadcast, then SIGZOMBIE is broadcast to force reaping of zombie sessions. This tells these sessions (usually aliased ``daemon'' sessions) that nothing is left to do, and they're as good as dead anyway. It's normal for aliased sessions to receive IDLE and ZOMBIE when all the sessions that may use them have gone away. <UL> <LI> POE::Kernel::sig( $signal_name, $state_name ) The <CODE>sig()</CODE> method registers a state to handle a particular signal. Only one state in any given session may be registered for a particular signal. Registering a second state for the same signal will replace the previous state with the new one. Signals that don't have states will be dispatched to the _signal state instead. <LI> POE::Kernel::signal( $session, $signal_name ) The <CODE>signal()</CODE> method posts a signal event to a session. It uses the kernel's event queue, bypassing the operating system, so the signal's name is not limited to what the OS allows. For example, the kernel does something similar to post a fictitious ZOMBIE signal. <PRE> $kernel->signal($session, 'BOGUS'); # Not as bogus as it sounds.</PRE> </UL> <H2><A NAME="process management methods">Process Management Methods</A></H2> POE's signal handling is Perl's signal handling, which means that POE won't safely handle signals as long as Perl has a problem with them. However, POE works around this in at least SIGCHLD's case by providing a ``safe'' <A HREF="../../../lib/Pod/perlfunc.html#item_fork"><CODE>fork()</CODE></A> function. &POE::Kernel::fork() blocks $SIG{'CHLD','CLD'} and starts an event loop to poll for expired child processes. It emulates the system's SIGCHLD behavior by sending a ``soft'' CHLD signal to the appropriate session. Because POE knows which session called its version of fork(), it can signal just that session that its forked child process has completed. Note: The first &POE::Kernel::fork call disables POE's usual SIGCHLD handler, so that the poll loop can reap children safely. Mixing plain fork and &POE::Kernel::fork isn't recommended. <UL> <LI> POE::Kernel::fork( ) The <A HREF="../../../lib/Pod/perlfunc.html#item_fork"><CODE>fork()</CODE></A> method tries to fork a process in the usual Unix way. In addition, it blocks SIGCHLD and/or SIGCLD and starts an event loop to poll for completed child processes. POE's <A HREF="../../../lib/Pod/perlfunc.html#item_fork"><CODE>fork()</CODE></A> will return different things in scalar and list contexts. In scalar context, it returns the child PID, 0, or undef, just as Perl's <A HREF="../../../lib/Pod/perlfunc.html#item_fork"><CODE>fork()</CODE></A> does. In a list context, it returns three items: the child PID (or 0 or undef), the numeric version of $!, and the string version of $!. </UL> <H2><A NAME="state management methods">State Management Methods</A></H2> The kernel's state management method lets sessions add, change and remove states at runtime. Wheels use this to add and remove select states from sessions when they're created and destroyed. <UL> <LI> POE::Kernel::state( $state_name, $code_reference ) POE::Kernel::state( $method_name, $object_reference ) POE::Kernel::state( $function_name, $package_name ) POE::Kernel::state( $state_name, $obj_or_package_ref, $method_name ) The <CODE>state()</CODE> method has three different uses, each for adding, updating or removing a different kind of state. It manipulates states in the current session. The three-parameter version of <CODE>state()</CODE> registers an object or package state to a method with a different name. Normally the object or package method would need to be named after the state it catches. The <CODE>state()</CODE> method returns 1 on success. On failure, it returns 0 and sets $! to one of: <PRE> ESRCH - Somehow, the current session does not exist.</PRE> This function can only register or remove one state at a time. <UL> <LI> Inline States Inline states are manipulated with: <PRE> $kernel->state($state_name, $code_reference);</PRE> If $code_reference is undef, then $state_name will be removed. Any pending events destined for $state_name will be redirected to _default. <LI> Object States Object states are manipulated with: <PRE> $kernel->state($method_name, $object_reference);</PRE> If $object_reference is undef, then the $method_name state will be removed. Any pending events destined for $method_name will be redirected to _default. They can also be maintained with: <PRE> $kernel->state($state_name, $object_reference, $object_method);</PRE> For example, this maps a session's B«_start» state to the object's start_state method: <PRE> $kernel->state('_start', $object_reference, 'start_state');</PRE> <LI> Package States Package states are manipulated with: <PRE> $kernel->state($function_name, $package_name);</PRE> If $package_name is undef, then the $function_name state will be removed. Any pending events destined for $function_name will be redirected to _default. </UL> </UL> <H2><A NAME="id management methods">ID Management Methods</A></H2> POE generates a unique ID for the process, and it maintains unique serial numbers for every session. These functions retrieve various ID values. <UL> <LI> POE::Kernel::ID() Returns a unique ID for this POE process. <PRE> my $process_id = $kernel->ID();</PRE> <LI> POE::Kernel::ID_id_to_session( $id ); Returns a session reference for the given ID. It returns undef if the ID doesn't exist. This allows programs to uniquely identify a particular Session (or detect that it's gone) even if Perl reuses the Session reference later. <LI> POE::Kernel::ID_session_to_id( $session ); Returns an ID for the given POE::Session reference, or undef ith the session doesn't exist. Perl reuses Session references fairly frequently, but Session IDs are unique. Because of this, the ID of a given reference (stringified, so Perl can release the referenced Session) may appear to change. If it does appear to have changed, then the Session reference is probably invalid. </UL> <HR> <H1><A NAME="see also">SEE ALSO</A></H1> POE; POE::Session <HR> <H1><A NAME="bugs">BUGS</A></H1> Oh, probably some. <HR> <H1><A NAME="authors & copyrights">AUTHORS & COPYRIGHTS</A></H1> Please see the POE manpage. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> POE::Kernel - POE Event Queue and Resource Manager </TD></TR> </TABLE> </BODY> </HTML>