1Proc::Fork(3) User Contributed Perl Documentation Proc::Fork(3)
2
6 Proc::Fork - simple, intuitive interface to the fork() system call
7
9 use Proc::Fork;
10 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
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 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 # 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 If the code in any of the clauses does not die or exit, it will
58 continue execution after the fork block.
59
61 All of the following functions are exported by default:
62 run_fork
64 run_fork { ... }
65 Performs the fork operation configured in its block.
67 child
69 child { ... }
70 Declares the block that should run in the child process.
72 parent
74 parent { ... }
75 Declares the block that should run in the parent process. The child's
77 PID is passed as an argument to the block.
78 retry
80 retry { ... }
81 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 This can be used to implement a wait-and-retry logic that may be
88 essential for some applications like daemons.
89 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 error
94 error { ... }
95 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 If an "error" clause is not used, errors will raise an exception using
101 "die".
102
104 The distribution includes the following examples as separate files in
105 the eg/ directory:
106 Simple example with IPC via pipe
108 use strict;
109 use Proc::Fork;
110 use IO::Pipe;
112 my $p = IO::Pipe->new;
113 run_fork {
115 parent {
116 my $child = shift;
117 $p->reader;
118 print while <$p>;
119 waitpid $child,0;
120 }
121 child {
122 $p->writer;
123 print $p "Line 1\n";
124 print $p "Line 2\n";
125 exit;
126 }
127 retry {
128 if( $_[0] < 5 ) {
129 sleep 1;
130 return 1;
131 }
132 return 0;
133 }
134 error {
135 die "That's all folks\n";
136 }
137 };
138 Multi-child example
140 use strict;
141 use Proc::Fork;
142 use IO::Pipe;
143 my $num_children = 5; # How many children we'll create
145 my @children; # Store connections to them
146 $SIG{CHLD} = 'IGNORE'; # Don't worry about reaping zombies
147 # Spawn off some children
149 for my $num ( 1 .. $num_children ) {
150 # Create a pipe for parent-child communication
151 my $pipe = IO::Pipe->new;
152 # Child simply echoes data it receives, until EOF
154 run_fork { child {
155 $pipe->reader;
156 my $data;
157 while ( $data = <$pipe> ) {
158 chomp $data;
159 print STDERR "child $num: [$data]\n";
160 }
161 exit;
162 } };
163 # Parent here
165 $pipe->writer;
166 push @children, $pipe;
167 }
168 # Send some data to the kids
170 for ( 1 .. 20 ) {
171 # pick a child at random
172 my $num = int rand $num_children;
173 my $child = $children[$num];
174 print $child "Hey there.\n";
175 }
176 Daemon example
178 use strict;
179 use Proc::Fork;
180 use POSIX;
181 # One-stop shopping: fork, die on error, parent process exits.
183 run_fork { parent { exit } };
184 # Other daemon initialization activities.
186 $SIG{INT} = $SIG{TERM} = $SIG{HUP} = $SIG{PIPE} = \&some_signal_handler;
187 POSIX::setsid() == -1 and die "Cannot start a new session: $!\n";
188 close $_ for *STDIN, *STDOUT, *STDERR;
189 # rest of daemon program follows
191 Forking socket-based network server example
193 use strict;
194 use IO::Socket::INET;
195 use Proc::Fork;
196 $SIG{CHLD} = 'IGNORE';
198 my $server = IO::Socket::INET->new(
200 LocalPort => 7111,
201 Type => SOCK_STREAM,
202 Reuse => 1,
203 Listen => 10,
204 ) or die "Couln't start server: $!\n";
205 my $client;
207 while ($client = $server->accept) {
208 run_fork { child {
209 # Service the socket
210 sleep(10);
211 print $client "Ooga! ", time % 1000, "\n";
212 exit; # child exits. Parent loops to accept another connection.
213 } }
214 }
215
217 Aristotle Pagaltzis <pagaltzis@gmx.de>
218 Documentation by Eric J. Roode.
220
222 This software is copyright (c) 2018 by Aristotle Pagaltzis. Its
223 documentation is copyright (c) 2002 by Eric J. Roode.
224 This is free software; you can redistribute it and/or modify it under
226 the same terms as the Perl 5 programming language system itself.
227perl v5.36.0 2023-01-20 Proc::Fork(3)