POE::Component::Daemon - Handles all the housework for a daemon.
use POE::Component::Daemon; POE::Component::Daemon->spawn(detach=>1, max_children=>3); # Create a session that uses SocketFactory POE::Session->create( inline_states=>{ _start=>sub { # catch this message from Daemon session $kernel->sig('daemon_child'=>'request'); # create a POE::Wheel::SocketFactory or whatever # ..... }, # socketfactory got a connection handle it here accept=>sub { # tell Daemon session about this Daemon->update_status('req', $info); }, ############### # we are now the child process (via the sig() in _start request=>sub { my($heap, $info)=@_[HEAP, ARG1]; # $info was passed here from accept accept # create POE::Wheel::ReadWrite .... # tell Daemon session that this request will take a long time Daemon->update_status('long'); }, ############### # The request is finished finished=>sub { return unless $heap->{done}; # tell Deamon session that this request is done $poe_kernel->post(Daemon=>'update_status', 'done'); }, });
Dealing with all the little details of a forking daemon can be annoying and hard. POE::Component::Daemon encapsulates all the details into one place and (hopefully) gets them right.
POE::Component::Daemon will deal with all the annoying details of creating and maintaining daemon processes. It can detach from the console, handle pre-forking pools or post-forking (ie, fork on each request). It will also redirect STDERR to a log file if asked.
POE::Component::Daemon also babysits child processes, handling their CHLD. POE::Component::Daemon can also makes sure requests don't take to long. If they do, it will try to get rid of them. See "BABYSITING" below.
CHLD
POE::Component::Daemon does not handle listening on sockets. That is up to your code.
Like all of POE, POE::Component::Daemon works cooperatively. It is up your code to tell POE::Component::Daemon when it is time to fork, block incoming requests when approriate and so on.
Sub-processes are maintained with the help of a scoreboard. In some situations, your code will have to update it's status in scoreboard with the "update_status" method.
Post-forking is the model that most examples and tutorials use. The daemon listens on a socket (or other mechanism) for new requests. When a new request comes in, a child process is forked off to handle that request and the parent process continues to listen for new requests.
If you are using a post-forking model, your code must inform POE::Component::Daemon about a new request. POE::Component::Daemon will then handle all the details of forking, and then broadcast a daemon_child signal, which is your cue that you can now handle the request.
This means the following steps are done.
Create SocketFactory wheel Create POE::Component::Daemon Receive SocketFactory's SuccessEvent Tell POE::Component::Daemon we are in a request (L</update_status>) POE::Component::Daemon forks POE::Component::Daemon sends daemon_child signal Receive daemon_child signal, create ReadWrite wheel Close SocketFactory wheel Talk with remote process When done, close ReadWrite wheel Tell POE::Component::Daemon we are no longer in a request POE::Component::Daemon will then shutdown this child process (signal daemon_shutdown).
Additionnaly, when POE::Component::Daemon detects that there are nearly too many child processes, it will send a "daemon_pause" signal. You should call "accept_pause" in POE::Wheel::SocketFactory. When the number of child processes drops back down, POE::Component::Daemon will then send a daemon_accept signal. You should then call "accept_resume" in POE::Wheel::SocketFactory.
daemon_accept
The graph in forking-flow.png might (or might not) help you understand the above.
The pre-forking model creates a pool of child processes before accepting requests. This is done so that each request doesn't incure the overhead of forking before it can be processed. It also allows a child process to handle more then one request. This is the model used by Apache.
When pre-forking, you create your SocketFactory and immediately pause it with "accept_pause" in POE::Wheel::SocketFactory. Then spawn a POE::Component::Daemon. and allow the kernel to run. POE::Component::Daemon will fork off the desired initial number of sub-processes (start_children). The child processes will be told they are children with a "daemon_child" signal. Your code then does what it needs and updates the status to 'wait' ("update_status"). When POE::Component::Daemon sees this, it fires off a "daemon_accept" signal. Your code would then unpause the socket, with "accept_resume" in POE::Wheel::SocketFactory.
start_children
When you receive a new connection, the status to 'req' or 'long' (if it's a long running request) and handle the request. When done, update the status to 'done' (or 'wait'). POE::Component::Daemon sees this, and will either send another "daemon_accept" signal to say it's time to start again or shutdown the daemon if this child has handled enough requests.
Note that when you receive a new request, you should pause your SocketFactory or you could receive more than one request at the same time AND ALL SORTS OF HIGGLY-PIGGLE WILL BE UNLEASHED on your code.
In list form, that gives us:
Spawn POE::Component::Daemon Spawn your session Create SocketFactory wheel, and pause it Getting a daemon_child signal means we are now a child process. Update status to 'wait' Get a daemon_accept signal Resume the SocketFactory wheel Receive SocketFactory's SuccessEvent Close the SocketFactory Update status to 'req' Create a ReadWrite wheel Talk with remote process When done, close the ReadWrite wheel Update status to 'done' Wait for daemon_accept or daemon_shutdown signal
The graph in preforking-flow.png might (or might not) help you understand the above.
It is of course possible to use this code in a non-forking server. While most functionnality of POE::Component::Daemon will be useless, methods like "drop_privs", "detach" and "peek" are useful.
Babysiting is the action of periodically monitoring all child processes to make sure none of them do anything bad. For values of 'bad' limited to going rogue (using too much CPU) or disapearing without a trace. Rogue processes are killed after 10 minutes.
Babysiting is activated with the babysit parameter to "spawn".
babysit
Babysiting doesn't have a test case and is probably badly implemented. Patches welcome.
POE::Component::Daemon->spawn( %params );
Where %params may contain:
%params
POE session alias for POE::Component::Daemon. Defaults to 'Daemon'. If you change it, other code that depends on it might be confused.
If true, POE::Component::Daemon will detach from the current process tree. It does this by forking twice and the grand-child then calls "setsid" in POSIX. Parent and grand-parent summarily exit.
Default is to not detach.
Name of the log file. STDERR and STDOUT are redirected to this file. You need to set logfile if you want detach from the current terminal.
The logfile will be closed and reopened on a HUP signal.
HUP
Turn on verbose messages. If set, babysiting and process creation will output some details to STDERR.
Maximum number of child processes that POE::Component::Daemon may create.
If set, but not start_children, then POE::Component::Daemon acts as a post-forking daemon. Note that it is unfortunately possible for POE::Component::Daemon to create more then max_children post-forking processes but instances of this should be rare.
max_children
In pre-forking mode, defaults to start_children + max_spare.
If set, then POE::Component::Daemon acts as a pre-forking daemon. At startup, POE::Component::Daemon will fork off start_children child processes.
Used by pre-forking server to decide when to create more child processes. If there are fewer than min_spare, it creates a new spare. If there are more than max_spare, some of the spares killed off with TERM.
max_spare defaults to 80% of max_children. min_spare defaults to 20% of max_children.
max_spare
min_spare
The number of requests each child process is allowed to handle before it is killed off. Limiting the number of requests prevents child processes from consuming too much memory or other resource.
Time, in seconds, between checks for rogue processes. See "BABYSITING" above.
Daemon->shutdown; $poe_kernel->post( Daemon=>'shutdown' ); $poe_kernel->signal( $poe_kernel=>'shutdown' );
Tell POE::Component::Daemon to shutdown. POE::Component::Daemon responds by cleaning up all traces in the kernel and broadcasting the "daemon_shutdown" signal. In the parent process, it sends a TERM signal to all child processes.
TERM
Daemon->update_status( $new_status, $data ) $poe_kernel->post( Daemon=>'update_status', $new_status, $data );
Tell POE::Component::Daemon your new status. $new_status is one of the scoreboards states, as discussed below. $data is useful information for a post-forking server moving into the 'req' state. See below.
$new_status
$data
Daemon->status()
Returns a string containing human readable information about the status of the daemon, including the current state of the scoreboard.
Daemon->foreign_child( $pid );
Allows you to report a child process that you might have spawned with POE::Component::Daemon. This obviates the need for you to have a CHLD handler. They will receive a TERM when current process exists.
Daemon->peek( $verbose );
Outputs the internal status of the POE::Kernel, with special attention paid to the reasons why a kernel won't exit.
If $verbose is false, only returns the event queue. If $verbose is set, details of each session are also output.
$verbose
In void context, outputs the status to STDERR. Otherwise outputs a big, human-readable string.
One helluva useful feature is to tie USR2 to the verbose output.
$poe_kernel->state( USR2 => sub { Daemon->peek( 1 ) } ); $poe_kernel->sig( USR2 => 'USR2' );
Now, instead of cursing the $GODS because your kernel doesn't exit when you think it should, you simply type the following in another window.
kill -USR2 I<pid> # or, if you are on Solaris or Linux pkill -USR2 -o your-daemon
POE::Component::Daemon uses a scoreboard to keep track of child processes. In a few situations, you must update the scoreboard to tell POE::Component::Daemon when certain events occur. You do this with "update_status"
Daemon->update_status( 'req', { handle=>$handle } ); $poe_kernel->call( Daemon=>'update_status', 'long' );
To find out when and why you should set your status, please read the "PRE-FORKING" and "POST-FORKING" sections above.
Process is handling a request. In a post-forking server, any extra data is sent back via daemon_child.
Process is handling a long request. Differentiating between normal and long requests can help the babysitter detect rogue processes.
In a post-forking server, any extra data is sent back via daemon_child
Process is waiting for next request.
Slot is empty.
Process is exiting.
Process is forking, but we are still in the parent
Process is forking, we are in the child.
Process is waiting for first request.
POE::Component::Daemon uses signals to communicate with other sessions. If you are interested in a given signal, simply register a handler with the kernel.
$poe_kernel->sig( $some_signal => $event );
The following signals are defined:
Posted from POE::Component::Daemon's _start event.
The current process is the parent. This is sent by a pre-forking daemon when all the initial children have been forked.
The current process is a child.
This is sent by a pre-forking daemon just after forking a new process. You must then update the status to 'wait'.
In post-forking daemon, this signal means that you may now handle the new request. ARG1 is the data you passed to update_status( 'req' ).
The current process is ready to accept new requests.
This is sent by a pre-forking daemon when the status is updated to 'wait'.
In post-forking daemon, this signal means that the number of child processes has fallen below the maximum and you may resume accepting new requests. Generally you do this by calling "accept_resume" in POE::Wheel::SocketFactory.
There are too many child processes. Do not accept any more requests. Generally you do this by calling "accept_pause" in POE::Wheel::SocketFactory.
Time to go to bed! Sent by POE::Component::Daemon when it thinks it's time to shutdown. This might be because of code called Daemon->shutdown or because of TERM or INT signals. Additionnaly, in a pre-forking server a shutdown is called when a child process has handled a certain number of requests.
We received a HUP signal. Any log files should be closed then reopenned.
Tested on Linux and FreeBSD. Reports for Mac OS, and other BSDs would be appreciated.
Doesn't support Windows.
POE
Philip Gwyn, <gwyn -AT- cpan.org>
Copyright 2004-2013 by Philip Gwyn. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install POE::Component::Daemon, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::Daemon
CPAN shell
perl -MCPAN -e shell install POE::Component::Daemon
For more information on module installation, please visit the detailed CPAN module installation guide.