1forks(3)              User Contributed Perl Documentation             forks(3)
2
3
4

NAME

6       forks - drop-in replacement for Perl threads using fork()
7

VERSION

9       This documentation describes version 0.36.
10

SYNOPSIS

12         use forks;    #ALWAYS LOAD AS FIRST MODULE, if possible
13         use warnings;
14
15         my $thread = threads->new( sub {       # or ->create or async()
16           print "Hello world from a thread\n";
17         } );
18
19         $thread->join;
20
21         $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
27         threads->detach;
28         $thread->detach;
29
30         my $tid    = $thread->tid;
31         my $owntid = threads->tid;
32
33         my $self    = threads->self;
34         my $threadx = threads->object( $tidx );
35
36         my @running = threads->list(threads::running);
37         $_->join() foreach (threads->list(threads::joinable));
38         $_->join foreach threads->list; #block until all threads done
39
40         unless (fork) {
41           threads->isthread; # could be used a child-init Apache handler
42         }
43
44         # Enable debugging
45         use forks qw(debug);
46         threads->debug( 1 );
47
48         # Stringify thread objects
49         use forks qw(stringify);
50
51         # 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
57         # Send a signal to a thread
58         $thr->kill('SIGUSR1');
59
60         # Manual deadlock detection
61         if ($thr->is_deadlocked()) {
62           print "Thread $thr is currently deadlocked!\n";
63         }
64
65         # Use forks as a drop-in replacement for an ithreads application
66         perl -Mforks threadapplication
67
68       See "SYNOPSIS" in threads for more examples.
69

DESCRIPTION

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
74       Refer to the threads module for ithreads API documentation.  Also, use
75
76           perl -Mforks -e 'print $threads::VERSION'
77
78       to see what version of threads you should refer to regarding supported
79       API features.
80
81       There were a number of goals that I am trying to reach with this
82       implementation.
83
84         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
92   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
98           perl -Mforks  script.pl
99
100   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
110   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
115   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
121       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
130   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
140       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
145   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
151       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
160       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
169       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
173   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
182       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
190       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

REQUIRED MODULES

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

IMPLEMENTATION

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
214   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

EXTRA CLASS METHODS

223       Apart from the standard class methods, the following class methods are
224       supplied by the "forks" threads implementation.
225
226   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
232       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
237       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
243   debug
244        threads->debug( 1 );
245        $debug = threads->debug;
246
247       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
252       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

EXTRA FEATURES

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
267       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
273       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
278   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
284   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
290       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
294       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
298       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
301       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
306           threads->new(sub {
307               $DB::fork_TTY = '/dev/tty003'; #tie thread to TTY 3
308               ...
309           });
310
311       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
317       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
320       2. Define subroutine DB::get_fork_TTY()
321
322       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
327       For example, to dynamically spawn a new xterm session and bind a new
328       thread to it, you could do the following:
329
330       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
336       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
340   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
347   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
356       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
362   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
369           THREADS_DAEMON_MODEL=1 perl -Mforks -MPOE threadapplication
370
371       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

NOTES

377       Some important items you should be aware of.
378
379   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
383       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
388   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
395       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
399       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
406   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
415       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
419           {
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
427       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
431   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
436       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
442       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
446           HUP INT PIPE TERM USR1 USR2 ABRT EMT QUIT TRAP
447
448   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
453           - As long as you modify signals using %SIG, you should never encounter any
454           unexpected issues.
455
456           - 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
463   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
470       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
477   $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
486   $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
496   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
503           _fork_pre
504           _fork
505           _fork_post_parent
506           _fork_post_child
507
508       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
512       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

CAVEATS

517       Some caveats that you need to be aware of.
518
519   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
525       You may decrease some latency by using UNIX sockets (see "UNIX socket
526       support").
527
528       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
532   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
539       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
546       However, two subtle behavior variances exist relative to native Perl
547       threads:
548
549           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
553           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
560       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
565   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
571   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
577   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

TODO

585       See the TODO file in the distribution.
586

KNOWN PROBLEMS

588       These problems are known and will hopefully be fixed in the future:
589
590       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
598         And of course, there might be other, undiscovered issues.  Patches
599         are welcome!
600

CREDITS

602       Refer to the "CREDITS" file included in the distribution.
603

CURRENT AUTHOR AND MAINTAINER

605       Eric Rybski <rybskej@yahoo.com>.  Please send all module inquries to
606       me.
607

ORIGINAL AUTHOR

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

SEE ALSO

619       threads, forks::BerkeleyDB, Apache::forks.
620
621
622
623perl v5.38.0                      2023-07-21                          forks(3)
Impressum