1forks(3) User Contributed Perl Documentation forks(3)
2
6 forks - drop-in replacement for Perl threads using fork()
7
9 This documentation describes version 0.36.
10
12 use forks; #ALWAYS LOAD AS FIRST MODULE, if possible
13 use warnings;
14 my $thread = threads->new( sub { # or ->create or async()
16 print "Hello world from a thread\n";
17 } );
18 $thread->join;
20 $thread = threads->new( { 'context' => 'list' }, sub {
22 print "Thread is expected to return a list\n";
23 return (1, 'abc', 5);
24 }
25 my @result = $thread->join();
26 threads->detach;
28 $thread->detach;
29 my $tid = $thread->tid;
31 my $owntid = threads->tid;
32 my $self = threads->self;
34 my $threadx = threads->object( $tidx );
35 my @running = threads->list(threads::running);
37 $_->join() foreach (threads->list(threads::joinable));
38 $_->join foreach threads->list; #block until all threads done
39 unless (fork) {
41 threads->isthread; # could be used a child-init Apache handler
42 }
43 # Enable debugging
45 use forks qw(debug);
46 threads->debug( 1 );
47 # Stringify thread objects
49 use forks qw(stringify);
50 # Check state of a thread
52 my $thr = threads->new( ... );
53 if ($thr->is_running()) {
54 print "Thread $thr running\n"; #prints "Thread 1 running"
55 }
56 # Send a signal to a thread
58 $thr->kill('SIGUSR1');
59 # Manual deadlock detection
61 if ($thr->is_deadlocked()) {
62 print "Thread $thr is currently deadlocked!\n";
63 }
64 # Use forks as a drop-in replacement for an ithreads application
66 perl -Mforks threadapplication
67 See "SYNOPSIS" in threads for more examples.
69
71 The "forks" pragma allows a developer to use threads without having to
72 have a threaded perl, or to even run 5.8.0 or higher.
73 Refer to the threads module for ithreads API documentation. Also, use
75 perl -Mforks -e 'print $threads::VERSION'
77 to see what version of threads you should refer to regarding supported
79 API features.
80 There were a number of goals that I am trying to reach with this
82 implementation.
83 Using this module only makes sense if you run on a system that has an
85 implementation of the "fork" function by the Operating System.
86 Windows is currently the only known system on which Perl runs which
87 does not have an implementation of "fork". Therefore, it doesn't
88 make any sense to use this module on a Windows system. And
89 therefore, a check is made during installation barring you from
90 installing on a Windows system.
91 module load order: forks first
93 Since forks overrides core Perl functions, you are *strongly*
94 encouraged to load the forks module before any other Perl modules.
95 This will insure the most consistent and stable system behavior. This
96 can be easily done without affecting existing code, like:
97 perl -Mforks script.pl
99 memory usage
101 The standard Perl 5.8.0 threads implementation is very memory
102 consuming, which makes it basically impossible to use in a production
103 environment, particularly with mod_perl and Apache. Because of the use
104 of the standard Unix fork() capabilities, most operating systems will
105 be able to use the Copy-On-Write (COW) memory sharing capabilities
106 (whereas with the standard Perl 5.8.0 threads implementation, this is
107 thwarted by the Perl interpreter cloning process that is used to create
108 threads). The memory savings have been confirmed.
109 mod_perl / Apache
111 This threads implementation allows you to use a standard, pre-forking
112 Apache server and have the children act as threads (with the class
113 method "isthread").
114 same API as threads
116 You should be able to run threaded applications unchanged by simply
117 making sure that the "forks" and "forks::shared" modules are loaded,
118 e.g. by specifying them on the command line. Forks is currently API
119 compatible with CPAN threads version 1.53.
120 Additionally, you do not need to worry about upgrading to the latest
122 Perl maintenance release to insure that the (CPAN) release of threads
123 you wish to use is fully compatibly and stable. Forks code is
124 completely independent of the perl core, and thus will guarantee
125 reliable behavior on any release of Perl 5.8 or later. (Note that
126 there may be behavior variances if running under Perl 5.6.x, as that
127 version does not support safe signals and requires a source filter to
128 load forks).
129 using as a development tool
131 Because you do not need a threaded Perl to use forks.pm, you can start
132 prototyping threaded applications with the Perl executable that you are
133 used to. Just download and install the "forks" package from CPAN. So
134 the threshold for trying out threads in Perl has become much lower.
135 Even Perl 5.005 should, in principle, be able to support the forks.pm
136 module; however, some issues with regards to the availability of XS
137 features between different versions of Perl, it seems that 5.6.0
138 (unthreaded) is what you need at least.
139 Additionally, forks offers a full thread deadlock detection engine, to
141 help discover and optionally resolve locking issues in threaded
142 applications. See "Deadlock detection and resolution" in forks::shared
143 for more information.
144 using in production environments
146 This package has successfully been proven as stable and reliable in
147 production environments. I have personally used it in high-
148 availability, database-driven, message processing server applications
149 since 2004 with great success.
150 Also, unlike pure ithreads, forks.pm is fully compatible with all perl
152 modules, whether or not they have been updated to be ithread safe.
153 This means that you do not need to feel limited in what you can develop
154 as a threaded perl application, a problem that continues to plague the
155 acceptance of ithreads in production enviroments today. Just handle
156 these modules as you would when using a standard fork: be sure to
157 create new instances of, or connections to, resources where a single
158 instance can not be shared between multiple processes.
159 The only major concern is the potentially slow (relative to pure
161 ithreads) performance of shared data and locks. If your application
162 doesn't depend on extensive semaphore use, and reads/writes from shared
163 variables moderately (such as using them primarily to deliver data to a
164 child thread to process and the child thread uses a shared structure to
165 return the result), then this will likely not be an issue for your
166 application. See the TODO section regarding plans to tackle this
167 issue.
168 Also, you may wish to try forks::BerkeleyDB, which has shown
170 signifigant performance gains and consistent throughoutput in high-
171 concurrency shared variable applications.
172 Perl built without native ithreads
174 If your Perl release was not built with ithreads or does not support
175 ithreads, you will have a compile-time option of installing forks into
176 the threads and threads::shared namespaces. This is done as a
177 convenience to give users a reasonably seamless ithreads API experience
178 without having to rebuild their distribution with native threading (and
179 its slight performance overhead on all perl runtime, even if not using
180 threads).
181 Note: When using forks in this manner (e.g. "use threads;") for the
183 first time in your code, forks will attempt to behave identically to
184 threads relative to the current version of threads it supports (refer
185 to $threads::VERSION), even if the behavior is (or was) considered a
186 bug. At this time, this means that shared variables will lose their
187 pre-existing value at the time they are shared and that splice will die
188 if attempted on a shared scalar.
189 If you use forks for the first time as "use forks" and other loaded
191 code uses "use threads", then this threads behavior emulation does not
192 apply.
193
195 Acme::Damn (any)
196 Attribute::Handlers (any)
197 Devel::Symdump (any)
198 File::Spec (any)
199 if (any)
200 IO::Socket (1.18)
201 List::MoreUtils (0.15)
202 Scalar::Util (1.11)
203 Storable (any)
204 Sys::SigAction (0.11)
205 Test::More (any)
206 Time::HiRes (any)
207
209 This version is mostly written in Perl. Inter-process communication is
210 done by using sockets, with the process that stores the shared
211 variables as the server and all the processes that function as threads,
212 as clients.
213 why sockets?
215 The reason I chose sockets for inter-thread communication above using a
216 shared memory library, is that a blocking socket allows you to
217 elegantly solve the problem of a thread that is blocking for a certain
218 event. Any polling that might occur, is not occurring at the Perl
219 level, but at the level of the socket, which should be much better and
220 probably very optimized already.
221
223 Apart from the standard class methods, the following class methods are
224 supplied by the "forks" threads implementation.
225 isthread
227 unless (fork) {
228 threads->isthread; # this process is a detached thread now
229 exit; # can not return values, as thread is detached
230 }
231 The "isthread" class method attempt to make a connection with the
233 shared variables process. If it succeeds, then the process will
234 function as a detached thread and will allow all the threads methods to
235 operate.
236 This method is mainly intended to be used from within a child-init
238 handler in a pre-forking Apache server. All the children that handle
239 requests become threads as far as Perl is concerned, allowing you to
240 use shared variables between all of the Apache processes. See
241 Apache::forks for more information.
242 debug
244 threads->debug( 1 );
245 $debug = threads->debug;
246 The "debug" class method allows you to (re)set a flag which causes
248 extensive debugging output of the communication between threads to be
249 output to STDERR. The format is still subject to change and therefore
250 still undocumented.
251 Debugging can only be switched on by defining the environment variable
253 "THREADS_DEBUG". If the environment variable does not exist when the
254 forks.pm module is compiled, then all debugging code will be optimised
255 away to create a better performance. If the environment variable has a
256 true value, then debugging will also be enabled from the start.
257
259 Native threads 'to-the-letter' emulation mode
260 By default, forks behaves slightly differently than native ithreads,
261 regarding shared variables. Specifically, native threads does not
262 support splice() on shared arrays, nor does it retain any pre-existing
263 values of arrays or hashes when they are shared; however, forks
264 supports all of these functions. These are behaviors are considered
265 limitations/bugs in the current native ithread implementation.
266 To allow for complete drop-in compatibility with scripts and modules
268 written for threads.pm, you may specify the environment variable
269 "THREADS_NATIVE_EMULATION" to a true value before running your script.
270 This will instruct forks to behave exactly as native ithreads would in
271 the above noted situations.
272 This mode may also be enabled by default (without requiring this
274 environment variable if you do not have a threaded Perl and wish to
275 install forks as a full drop-in replacement. See "Perl built without
276 native ithreads" for more information.
277 Deadlock detection
279 Forks also offers a full thread deadlock detection engine, to help
280 discover and optionally resolve locking issues in threaded
281 applications. See "Deadlock detection and resolution" in forks::shared
282 for more information.
283 Perl debugger support
285 Forks supports basic compabitility with the Perl debugger. By default,
286 only the main thread to the active terminal (TTY), allowing for
287 debugging of scripts where child threads are run as background tasks
288 without any extra steps.
289 If you wish to debug code executed in child threads, you may need to
291 perform a few steps to prepare your environment for multi-threaded
292 debugging.
293 The simplest option is run your script in xterm, as Perl will
295 automatically create additional xterm windows for each child thread
296 that encounters a debugger breakpoint.
297 Otherwise, you will need to manually tell Perl how to map a control of
299 thread to a TTY. Two undocumented features exist in the Perl debugger:
300 1. Define global variable $DB::fork_TTY as the first stem in the
302 subroutine for a thread. The value must be a valid TTY name, such as
303 '/dev/pts/1' or '/dev/ttys001'; valid names may vary across platforms.
304 For example:
305 threads->new(sub {
307 $DB::fork_TTY = '/dev/tty003'; #tie thread to TTY 3
308 ...
309 });
310 Also, the TTY must be active and idle prior to the thread executing.
312 This normally is accomplished by opening a new local or remote session
313 to your machine, identifying the TTY via `tty`, and then typing `sleep
314 10000000` to prevent user input from being passed to the command line
315 while you are debugging.
316 When the debugger halts at a breakpoint in your code in a child thread,
318 all output and user input will be managed via this TTY.
319 2. Define subroutine DB::get_fork_TTY()
321 This subroutine will execute once each child thread as soon as it has
323 spawned. Thus, you can create a new TTY, or simply bind to an existng,
324 active TTY. In this subroutine, you should define a unique, valid TTY
325 name for the global variable $DB::fork_TTY.
326 For example, to dynamically spawn a new xterm session and bind a new
328 thread to it, you could do the following:
329 sub DB::get_fork_TTY {
331 open XT, q[3>&1 xterm -title 'Forked Perl debugger' -e sh -c
332 'tty1>&3;\ sleep 10000000' |];
333 $DB::fork_TTY = <XT>;
334 chomp $DB::fork_TTY; }
335 For more information and tips, refer to this excellent Perl Monks
337 thread: "/www.perlmonks.org/?node_id=128283"" in <a
338 href="http:Debugging Several Proccesses at Same Time</a>>.
339 INET socket IP mask
341 For security, inter-thread communication INET sockets only will allow
342 connections from the default local machine IPv4 loopback address (e.g
343 127.0.0.1). However, this filter may be modified by defining the
344 environment variable "THREADS_IP_MASK" with a standard perl regular
345 expression (or with no value, which would disable the filter).
346 UNIX socket support
348 For users who do not wish to (or can not) use TCP sockets, UNIX socket
349 support is available. This can be only switched on by defining the
350 environment variable "THREADS_SOCKET_UNIX". If the environment
351 variable has a true value, then UNIX sockets will be used instead of
352 the default TCP sockets. Socket descriptors are currently written to
353 /var/tmp and given a+rw access by default (for cleanest functional
354 support on multi-user systems).
355 This feature is excellent for applications that require extra security,
357 as it does not expose forks.pm to any INET vunerabilities your system
358 may be subject to (i.e. systems not protected by a firewall). It also
359 may provide an additional performance boost, as there is less system
360 overhead necessary to handle UNIX vs INET socket communication.
361 Co-existance with fork-aware modules and environments
363 For modules that actively monitor and clean up after defunct child
364 processes like POE, forks has added support to switch the methodology
365 used to maintain thraad group state. This feature is switched on by
366 defining the environment variable "THREADS_DAEMON_MODEL". An example
367 use might be:
368 THREADS_DAEMON_MODEL=1 perl -Mforks -MPOE threadapplication
370 This function essentially reverses the parent-child relationship
372 between the main thread and the thread state process that forks.pm
373 uses. Extra care has gone into retaining full system signal support
374 and compatibility when using this mode, so it should be quite stable.
375
377 Some important items you should be aware of.
378 Signal behavior
380 Unlike ithreads, signals being sent are standard OS signals, so you
381 should program defensively if you plan to use inter-thread signals.
382 Also, be aware that certain signals may untrappable depending on the
384 target platform, such as SIGKILL and SIGSTOP. Thus, it is recommended
385 you only use normal signals (such as TERM, INT, HUP, USR1, USR2) for
386 inter-thread signal handling.
387 exit() behavior
389 If you call exit() in a thread other than the main thread and exit
390 behavior is configured to cause entire application to exit (default
391 behavior), be aware that all other threads will be agressively
392 terminated using SIGKILL. This will cause END blocks and global
393 destruction to be ignored in those threads.
394 This behavior conforms to the expected behavior of native Perl threads.
396 The only subtle difference is that the main thread will be signaled
397 using SIGABRT to immediately exit.
398 If you call fork() but do not call <threads->isthread()>, then the
400 child process will default to the pre-existing CORE::GLOBAL::exit() or
401 CORE::exit() behavior. Note that such processes are exempt from
402 application global termination if exit() is called in a thread, so you
403 must manually clean up child processes created in this manner before
404 exiting your threaded application.
405 END block behavior
407 In native ithreads, END blocks are only executed in the thread in which
408 the code was loaded/evaluated. However, in forks, END blocks are
409 processed in all threads that are aware of such code segments (i.e.
410 threads started after modules with END blocks are loaded). This may be
411 considered a bug or a feature depending on what your END blocks are
412 doing, such as closing important external resources for which each
413 thread may have it's own handle.
414 In general, it is a good defensive programming practice to add the
416 following to your END blocks when you want to insure sure they only are
417 evaluated in the thread that they were created in:
418 {
420 my $tid = threads->tid if exists $INC{'threads.pm'};
421 END {
422 return if defined($tid) && $tid != threads->tid;
423 # standard end block code goes here
424 }
425 }
426 This code is completely compatible with native ithreads. Note that
428 this behavior may change in the future (at least with
429 THREADS_NATIVE_EMULATION mode).
430 Modifying signals
432 Since the threads API provides a method to send signals between threads
433 (processes), untrapped normal and error signals are defined by forks
434 with a basic exit() shutdown function to provide safe termination.
435 Thus, if you (or any modules you use) modify signal handlers, it is
437 important that the signal handlers at least remain defined and are not
438 undefined (for whatever reason). The system signal handler default,
439 usually abnormal process termination which skips END blocks, may cause
440 undesired behavior if a thread exits due to an unhandled signal.
441 In general, the following signals are considered "safe" to trap and use
443 in threads (depending on your system behavior when such signals are
444 trapped):
445 HUP INT PIPE TERM USR1 USR2 ABRT EMT QUIT TRAP
447 Modules that modify %SIG or use POSIX::sigaction()
449 To insure highest stability, forks ties some hooks into the global %SIG
450 hash to co-exist as peacefully as possible with user-defined signals.
451 This has a few subtle, but important implications:
452 - As long as you modify signals using %SIG, you should never encounter any
454 unexpected issues.
455 - If you use POSIX::sigaction, it may subvert protections that forks has
457 added to the signal handling system. In normal circumstances, this will not
458 create any run-time issues; however, if you also attempt to access shared
459 variables in signal handlers or END blocks, you may encounter unexpected
460 results. Note: if you do use sigaction, please avoid overloading the ABRT
461 signal in the main thread, as it is used for process group flow control.
462 Modules that modify $SIG{CHLD}
464 In order to be compatible with perl's core system() function on all
465 platforms, extra care has gone into implementing a smarter $SIG{CHLD}
466 in forks.pm. The only functional effect is that you will never need to
467 (or be able to) reap threads (processes) if you define your own CHLD
468 handler.
469 You may define the environment variable THREADS_SIGCHLD_IGNORE to to
471 force forks to use 'IGNORE' on systems where a custom CHLD signal
472 handler has been automatically installed to support correct exit code
473 of perl core system() function. Note that this should *not* be
474 necessary unless you encounter specific issues with the forks.pm CHLD
475 signal handler.
476 $thr->wantarray() returns void after $thr->join or $thr->detach
478 Be aware that thread return context is purged and $thr->wantarray will
479 return void context after a thread is detached or joined. This is done
480 to minimize memory in programs that spawn many (millions of) threads.
481 This differs from default threads.pm behavior, but should be acceptable
482 as the context no longer serves a functional purpose after a join or
483 detach. Thus, if you still require thread context information after a
484 join, be sure to request and store the value of $thr->wantarray first.
485 $thr->get_stack_size() returns default after $thr->join or $thr->detach
487 Thread stack size information is purged and $thr->get_stack_size will
488 return the current threads default after a thread is detached or
489 joined. This is done to minimize memory in programs that spawn many
490 (millions of) threads. This differs from default threads.pm behavior,
491 which retains per-thread stack size information indefinitely. Thus, if
492 you require individual thread stack size information after a join or
493 detach, be sure to request and store the value of $thr->get_stack_size
494 first.
495 Modules that modify CORE::GLOBAL::fork()
497 This modules goes to great lengths to insure that normal fork behavior
498 is seamlessly integrated into the threaded environment by overloading
499 CORE::GLOBAL::fork. Thus, please refrain from overloading this
500 function unless absolutely necessary. In such a case, forks.pm
501 provides a set of four functions:
502 _fork_pre
504 _fork
505 _fork_post_parent
506 _fork_post_child
507 that represent all possible functional states before and after a fork
509 occurs. These states must be called to insure that fork() works for
510 both threads and normal fork calls.
511 Refer to forks.pm source code, *CORE::GLOBAL::fork = sub { ... }
513 definition as an example usage. Please contact the author if you have
514 any questions regarding this.
515
517 Some caveats that you need to be aware of.
518 Greater latency
520 Because of the use of sockets for inter-thread communication, there is
521 an inherent larger latency with the interaction between threads.
522 However, the fact that TCP sockets are used, may open up the
523 possibility to share threads over more than one physical machine.
524 You may decrease some latency by using UNIX sockets (see "UNIX socket
526 support").
527 Also, you may wish to try forks::BerkeleyDB, which has shown
529 signifigant performance gains and consistent throughoutput in
530 applications requiring high-concurrency shared variable access.
531 Module CLONE & CLONE_SKIP functions and threads
533 In rare cases, module CLONE functions may have issues when being auto-
534 executed by a new thread (forked process). This only affects modules
535 that use XS data (objects or struts) created by to external C
536 libraries. If a module attempts to CLONE non-fork safe XS data, at
537 worst it may core dump only the newly created thread (process).
538 If CLONE_SKIP function is defined in a package and it returns a true
540 value, all objects of this class type will be undefined in new threads.
541 This is generally the same behavior as native threads with Perl 5.8.7
542 and later. See <<a
543 href="http://perldoc.perl.org/perlmod.html#Making-your-module-threadsafe-threadsafe-thread-safe-module%2c-threadsafe-module%2c-thread-safe-CLONE-CLONE_SKIP-thread-threads-ithread">perlmod</a>>
544 for more information.
545 However, two subtle behavior variances exist relative to native Perl
547 threads:
548 1. The actual undefining of variables occurs in the child thread. This should
550 be portable with all non-perl modules, as long as those module datastructures can be
551 safely garbage collected in the child thread (note that DESTROY will not be called).
552 2. Arrays and hashes will be emptied and unblessed, but value will not be converted
554 to an undef scalar ref. This differs from native threads, where all references
555 become an undef scalar ref. This should be generally harmless, as long as you are
556 careful with variable state checks (e.g. check whether reference is still blessed,
557 not whether the reftype has changed, to determine if it is still a valid object
558 in a new thread).
559 Overall, if you treat potentially sensitive resources (such as DBI
561 driver instances) as non-thread-safe by default and close these
562 resources prior to creating a new thread, you should never encounter
563 any portability issues.
564 Can't return unshared filehandles from threads
566 Currently, it is not possible to return a file handle from a thread to
567 the thread that is joining it. Attempting to do so will throw a
568 terminal error. However, if you share the filehandle first with
569 forks::shared, you can safely return the shared filehandle.
570 Signals and safe-signal enabled Perl
572 In order to use signals, you must be using perl 5.8 compiled with safe
573 signal support. Otherwise, you'll get a terminal error like "Cannot
574 signal threads without safe signals" if you try to use signal
575 functions.
576 Source filter
578 To get forks.pm working on Perl 5.6.x, it was necessary to use a source
579 filter to ensure a smooth upgrade path from using forks under Perl
580 5.6.x to Perl 5.8.x and higher. The source filter used is pretty
581 simple and may prove to be too simple. Please report any problems that
582 you may find when running under 5.6.x.
583
585 See the TODO file in the distribution.
586
588 These problems are known and will hopefully be fixed in the future:
589 test-suite exits in a weird way
591 Although there are no errors in the test-suite, the test harness
592 sometimes thinks there is something wrong because of an unexpected
593 exit() value. This is an issue with Test::More's END block, which
594 wasn't designed to co-exist with a threads environment and forked
595 processes. Hopefully, that module will be patched in the future, but
596 for now, the warnings are harmless and may be safely ignored.
597 And of course, there might be other, undiscovered issues. Patches
599 are welcome!
600
602 Refer to the "CREDITS" file included in the distribution.
603
605 Eric Rybski <rybskej@yahoo.com>. Please send all module inquries to
606 me.
607
609 Elizabeth Mattijsen, <liz@dijkmat.nl>.
610
612 Copyright (c)
613 2005-2014 Eric Rybski <rybskej@yahoo.com>,
614 2002-2004 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved.
615 This program is free software; you can redistribute it and/or modify it
616 under the same terms as Perl itself.
617
619 threads, forks::BerkeleyDB, Apache::forks.
620perl v5.38.0 2023-07-21 forks(3)