NAME

Proc::Fork - Simple interface to fork() system call.

VERSION

This documentation describes version 0.05 of Fork.pm, March 15, 2002.

SYNOPSIS

 use Proc::Fork;

 child
 {
     # child code goes here.
 }
 parent
 {
     my $child_pid = shift;
     # parent code goes here.
     waitpid $child, 0;
 }
 error
 {
     # Error-handling code goes here (if fork() fails).
 };
 # Note the semicolon at the end. Necessary if other statements follow.

DESCRIPTION

This package provides a simple interface to fork().

The code for the parent, child, and (optional) error handler are grouped together in a "fork block". The clauses may appear in any order, but they must be consecutive (without any other statements in between).

The semicolon after the last clause is mandatory, unless the last clause is at the end of the enclosing block or file.

All three clauses need not be specified. If the error clause is omiitted, the program will die with a simple message if a fork error occurs. If the parent or child clause is omitted, the respective (parent or child) process will start execution after the final clause. So if one or the other only has to do some simple action, you need only specify that one. For example:

 # spawn off a child process to do some simple processing
 child {
     exec '/bin/ls', '-l';
     die "Couldn't exec ls: $!\n";
 };
 # Parent will continue execution from here
 # ...

If the code in any of the clauses does not die or exit, it will continue execution after the fork block.

FUNCTIONS

child

 child { ...code... }

This function forks, if the fork has not yet been done, and executes the code reference passed to it if it discovers that it is the child process.

If there is a fork error, and there is no error{} clause, this function dies with a simple error message (which will include $!).

parent

 parent { ...code... }

This function forks, if the fork has not yet been done, and executes the code reference passed to it if it discovers that it is the parent process.

If there is a fork error, and there is no error{} clause, this function dies with a simple error message (which will include $!).

error

 error { ...code... };

This optional function forks, if the fork has not yet been done, and executes the code reference passed to it if there was an error (ie, if fork returned undef). If an error clause is not used, parent or child will detect the fork error and will die.

SYNTAX NOTE

Imporant note: Due to the way Perl 5 parses these functions, there must be a semicolon after the close brace of the final clause, whether it be a parent, child, or error clause, unless that closing brace is the final token of the enclosing block or file.

Fork.pm attempts to detect missing semicolons. How well this works remains to be seen.

SIMPLE EXAMPLE

 # example with IPC via pipe
 use strict;
 use IO::Pipe;
 use Proc::Fork;
 my $p = new IO::Pipe;

 parent
 {
     my $child = shift;
     $p->reader;
     print while (<$p>);
     waitpid $child,0;
 }
 child
 {
     $p->writer;
     print $p "Line 1\n";
     print $p "Line 2\n";
     exit;
 }
 error
 {
     die "That's all folks\n";
 }

MULTI-CHILD EXAMPLE

 use strict;
 use Proc::Fork;
 use IO::Pipe;

 my $num_children = 5;    # How many children we'll create
 my @children;            # Store connections to them
 $SIG{CHLD} = 'IGNORE';   # Don't worry about reaping zombies

 # Spawn off some children
 for my $num (1..$num_children)
 {
     # Create a pipe for parent-child communication
     my $pipe = new IO::Pipe;

     # Child simply echoes data it receives, until EOF
     child
     {
         $pipe->reader;
         my $data;
         while ($data = <$pipe>)
         {
             chomp $data;
             print STDERR "child $num: [$data]\n";
         }
         exit;
     };

     # Parent here
     $pipe->writer;
     push @children, $pipe;
 }

 # Send some data to the kids
 for (1..20)
 {
     # pick a child at random
     my $num = int rand $num_children;
     my $child = $children[$num];
     print $child "Hey there.\n";
 }

DAEMON EXAMPLE

 # daemon example
 use strict;
 use Proc::Fork ();
 use Posix;

 # One-stop shopping: fork, die on error, parent process exits.
 Proc::Fork::parent {exit};

 # Other daemon initialization activities.
 close STDOUT; close STDERR; close STDIN;
 Posix::set_sid() or die "Cannot start a new session: $!\n";
 $SIG{INT} = $SIG{TERM} = $SIG{HUP} = $SIG{PIPE} = \&some_signal_handler;

 # rest of daemon program follows

INET SERVER EXAMPLE

 # Socket-based server example
 use strict;
 use IO::Socket::INET;
 use Proc::Fork;

 $SIG{CHLD} = 'IGNORE';

 my $server = IO::Socket::INET->new(LocalPort => 7111,  Type => SOCK_STREAM, Reuse => 1, Listen => 10)
     or die "Couln't start server: $!\n";

 my $client;
 while ($client = $server->accept)
 {
     child
     {
         # Service the socket
         sleep(10);
         print $client "Ooga! ", time % 1000, "\n";
         exit;    # child exits. Parent loops to accept another connection.
     }
 }

EXPORTS

This package exports the following symbols by default.

 child
 error
 parent

REQUIREMENTS

Carp.pm (included with Perl)

BUGS

None currently known. But that doesn't mean much.

AUTHOR / COPYRIGHT

Eric J. Roode, eric@myxa.com

Copyright (c) 2002 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

If you have suggestions for improvement, please drop me a line. If you make improvements to this software, I ask that you please send me a copy of your changes. Thanks.

cpanm Proc::Fork

perl -MCPAN -e shell
install Proc::Fork