1Proc::Fork(3)         User Contributed Perl Documentation        Proc::Fork(3)
2
3
4

NAME

6       Proc::Fork - simple, intuitive interface to the fork() system call
7

SYNOPSIS

9        use Proc::Fork;
10
11        run_fork {
12            child {
13                # child code goes here.
14            }
15            parent {
16                my $child_pid = shift;
17                # parent code goes here.
18                waitpid $child_pid, 0;
19            }
20            retry {
21                my $attempts = shift;
22                # what to do if fork() fails:
23                # return true to try again, false to abort
24                return if $attempts > 5;
25                sleep 1, return 1;
26            }
27            error {
28                # Error-handling code goes here
29                # (fork() failed and the retry block returned false)
30            }
31        };
32

DESCRIPTION

34       This module provides an intuitive, Perl-ish way to write forking
35       programs by letting you use blocks to illustrate which code section
36       executes in which fork. The code for the parent, child, retry handler
37       and error handler are grouped together in a "fork block". The clauses
38       may appear in any order, but they must be consecutive (without any
39       other statements in between).
40
41       All four clauses need not be specified. If the retry clause is omitted,
42       only one fork will be attempted. If the error clause is omitted the
43       program will die with a simple message if it can't retry. If the parent
44       or child clause is omitted, the respective (parent or child) process
45       will start execution after the final clause. So if one or the other
46       only has to do some simple action, you need only specify that one. For
47       example:
48
49        # spawn off a child process to do some simple processing
50        run_fork { child {
51            exec '/bin/ls', '-l';
52            die "Couldn't exec ls: $!\n";
53        } };
54        # Parent will continue execution from here
55        # ...
56
57       If the code in any of the clauses does not die or exit, it will
58       continue execution after the fork block.
59

INTERFACE

61       All of the following functions are exported by default:
62
63   run_fork
64        run_fork { ... }
65
66       Performs the fork operation configured in its block.
67
68   child
69        child { ... }
70
71       Declares the block that should run in the child process.
72
73   parent
74        parent { ... }
75
76       Declares the block that should run in the parent process. The child's
77       PID is passed as an argument to the block.
78
79   retry
80        retry { ... }
81
82       Declares the block that should run in case of an error, ie. if "fork"
83       returned "undef". If the code returns true, another "fork" is
84       attempted. The number of fork attempts so far is passed as an argument
85       to the block.
86
87       This can be used to implement a wait-and-retry logic that may be
88       essential for some applications like daemons.
89
90       If a "retry" clause is not used, no retries will be attempted and a
91       fork failure will immediately lead to the "error" clause being called.
92
93   error
94        error { ... }
95
96       Declares the block that should run if there was an error, ie when
97       "fork" returns "undef" and the "retry" clause returns false. The number
98       of forks attempted is passed as an argument to the block.
99
100       If an "error" clause is not used, errors will raise an exception using
101       "die".
102

EXAMPLES

104   Simple example with IPC via pipe
105        use strict;
106        use Proc::Fork;
107
108        use IO::Pipe;
109        my $p = IO::Pipe->new;
110
111        run_fork {
112            parent {
113                my $child = shift;
114                $p->reader;
115                print while <$p>;
116                waitpid $child,0;
117            }
118            child {
119                $p->writer;
120                print $p "Line 1\n";
121                print $p "Line 2\n";
122                exit;
123            }
124            retry {
125                if( $_[0] < 5 ) {
126                    sleep 1;
127                    return 1;
128                }
129                return 0;
130            }
131            error {
132                die "That's all folks\n";
133            }
134        };
135
136   Multi-child example
137        use strict;
138        use Proc::Fork;
139        use IO::Pipe;
140
141        my $num_children = 5;    # How many children we'll create
142        my @children;            # Store connections to them
143        $SIG{CHLD} = 'IGNORE';   # Don't worry about reaping zombies
144
145        # Spawn off some children
146        for my $num ( 1 .. $num_children ) {
147            # Create a pipe for parent-child communication
148            my $pipe = IO::Pipe->new;
149
150            # Child simply echoes data it receives, until EOF
151            run_fork { child {
152                $pipe->reader;
153                my $data;
154                while ( $data = <$pipe> ) {
155                    chomp $data;
156                    print STDERR "child $num: [$data]\n";
157                }
158                exit;
159            } };
160
161            # Parent here
162            $pipe->writer;
163            push @children, $pipe;
164        }
165
166        # Send some data to the kids
167        for ( 1 .. 20 ) {
168            # pick a child at random
169            my $num = int rand $num_children;
170            my $child = $children[$num];
171            print $child "Hey there.\n";
172        }
173
174   Daemon example
175        use strict;
176        use Proc::Fork;
177        use POSIX;
178
179        # One-stop shopping: fork, die on error, parent process exits.
180        run_fork { parent { exit } };
181
182        # Other daemon initialization activities.
183        $SIG{INT} = $SIG{TERM} = $SIG{HUP} = $SIG{PIPE} = \&some_signal_handler;
184        POSIX::setsid() == -1 and die "Cannot start a new session: $!\n";
185        close $_ for *STDIN, *STDOUT, *STDERR;
186
187        # rest of daemon program follows
188
189   Forking socket-based network server example
190        use strict;
191        use IO::Socket::INET;
192        use Proc::Fork;
193
194        $SIG{CHLD} = 'IGNORE';
195
196        my $server = IO::Socket::INET->new(
197            LocalPort => 7111,
198            Type      => SOCK_STREAM,
199            Reuse     => 1,
200            Listen    => 10,
201        ) or die "Couln't start server: $!\n";
202
203        my $client;
204        while ($client = $server->accept) {
205            run_fork { child {
206                # Service the socket
207                sleep(10);
208                print $client "Ooga! ", time % 1000, "\n";
209                exit; # child exits. Parent loops to accept another connection.
210            } }
211        }
212

AUTHOR

214       Aristotle Pagaltzis <pagaltzis@gmx.de>
215
216       Documentation by Eric J. Roode.
217
219       This documentation is copyright (c) 2002 by Eric J. Roode.
220
221       This software is copyright (c) 2018 by Aristotle Pagaltzis.
222
223       This is free software; you can redistribute it and/or modify it under
224       the same terms as the Perl 5 programming language system itself.
225
226
227
228perl v5.28.1                      2018-08-23                     Proc::Fork(3)
Impressum