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

NAME

6       forks::shared - drop-in replacement for Perl threads::shared with
7       forks()
8

SYNOPSIS

10         use forks;
11         use forks::shared;
12
13         my $variable : shared;
14         my @array    : shared;
15         my %hash     : shared;
16
17         share( $variable );
18         share( @array );
19         share( %hash );
20
21         $variable = shared_clone($non_shared_ref_value);
22         $variable = shared_clone({'foo' => [qw/foo bar baz/]});
23
24         lock( $variable );
25         cond_wait( $variable );
26         cond_wait( $variable, $lock_variable );
27         cond_timedwait( $variable, abs time );
28         cond_timedwait( $variable, abs time, $lock_variable );
29         cond_signal( $variable );
30         cond_broadcast( $variable );
31
32         bless( $variable, class name );
33
34         # Enable deadlock detection and resolution
35         use forks::shared deadlock => {
36           detect => 1,
37           resolve => 1
38         );
39         # or
40         threads::shared->set_deadlock_option(
41           detect  => 1,
42           resolve => 1
43         );
44

DESCRIPTION

46       The "forks::shared" pragma allows a developer to use shared variables
47       with threads (implemented with the "forks" pragma) without having to
48       have a threaded perl, or to even run 5.8.0 or higher.
49
50       "forks::shared" is currently API compatible with CPAN threads::shared
51       version 1.05.
52

EXPORT

54       "share", "shared_clone", "cond_wait", "cond_timedwait", "cond_signal",
55       "cond_broadcast", "is_shared", "bless"
56
57       See "EXPORT" in threads::shared for more information.
58

OBJECTS

60       forks::shared exports a version of bless() that works on shared
61       objects, such that blessings propagate across threads.  See
62       threads::shared for usage information and the forks test suite for
63       additional examples.
64

EXTRA FEATURES

66   Deadlock detection and resolution
67       In the interest of helping programmers debug one of the most common
68       bugs in threaded application software, forks::shared supports a full
69       deadlock detection and resolution engine.
70
71       Automated detection and resolution
72
73       There are two ways to enable these features: either at import time in a
74       use statement, such as:
75
76           use forks::shared deadlock => { OPTIONS }
77
78       or during runtime as a class method call to "set_deadlock_option",
79       like:
80
81           forks::shared->set_deadlock_option( OPTIONS );
82           #or
83           threads::shared->set_deadlock_option( OPTIONS );
84
85       where "OPTIONS" may be a combination of any of the following:
86
87           detect         => 1 (enable) or 0 (disable)
88           period         => number of seconds between asynchronous polls
89           resolve        => 1 (enable) or 0 (disable)
90
91       The "detect" option enables deadlock detection.  By itself, this option
92       enabled synchronous deadlock detection, which efficiently checks for
93       potential deadlocks at lock() time.  If any are detected and warnings
94       are enabled, it will print out details to "STDERR" like the following
95       example:
96
97           Deadlock detected:
98               TID   SV LOCKED   SV LOCKING   Caller
99                 1           3            4   t/forks06.t at line 41
100                 2           4            3   t/forks06.t at line 46
101
102       The "period" option, if set to a value greater than zero, is the number
103       of seconds between asynchronous deadlock detection checks.
104       Asynchronous detection is useful for debugging rare, time-critical race
105       conditions leading to deadlocks that may be masked by the slight time
106       overhead introduced by synchronous detection on each lock() call.
107       Overall, it is less CPU intensive than synchronous deadlock detection.
108
109       The "resolve" option enables auto-termination of one thread in each
110       deadlocked thread pair that has been detected.  As with the "detect"
111       option, "resolve" prints out the action it performs to STDERR, if
112       warnings are enabled.  NOTE: "resolve" uses SIGKILL to break deadlocks,
113       so this feature should not be used in environments where stability of
114       the rest of your application may be adversely affected by process death
115       in this manner.
116
117       For example:
118
119           use forks;
120           use forks::shared
121               deadlock => {detect=> 1, resolve => 1};
122
123       Manual detection
124
125       If you wish to check for deadlocks without enabling automated deadlock
126       detection, forks provides an additonal thread object method,
127
128           $thr->is_deadlocked()
129
130       that reports whether the thread in question is currently deadlocked.
131       This method may be used in conjunction with the "resolve" deadlock
132       option to auto-terminate offending threads.
133
134   Splice on shared array
135       As of at least threads::shared 1.05, the splice function has not been
136       implememted for arrays; however, forks::shared fully supports splice on
137       shared arrays.
138
139   share() doesn't lose value for arrays and hashes
140       In the standard Perl threads implementation, arrays and hashes are re-
141       initialized when they become shared (with the share()) function.  The
142       share() function of forks::shared does not initialize arrays and hashes
143       when they become shared with the share() function.
144
145       This could be considered a bug in the standard Perl implementation.  In
146       any case this is an inconsistency of the behaviour of threads.pm and
147       forks.pm.
148
149       If you do not have a natively threaded perl and you have installed and
150       are using forks in "threads.pm" override mode (where "use threads"
151       loads forks.pm), then this module will explicitly emulate the behavior
152       of standard threads::shared and lose value for arrays and hashes with
153       share().  Additionally, array splice function will become a no-op with
154       a warning.
155
156       You may also enable this mode by setting the environment variable
157       "THREADS_NATIVE_EMULATION" to a true value before running your script.
158       See "Native threads 'to-the-letter' emulation mode" in forks for more
159       information.
160

CAVIATS

162       Some caveats that you need to be aware of.
163
164       Storing CODE refs in shared variables
165         Since forks::shared requires Storable to serialize shared data
166         structures, storing CODE refs in shared variables is not enabled by
167         default (primarily for security reasons).
168
169         If need share CODE refs between threads, the minimum you must do
170         before storing CODE refs is:
171
172             $Storable::Deparse = $Storable::Eval = 1;
173
174         See "CODE_REFERENCES" in Storable for detailed information, including
175         potential security risks and ways to protect yourself against them.
176
177       test-suite exits in a weird way
178         Although there are no errors in the test-suite, the test harness
179         sometimes thinks there is something wrong because of an unexpected
180         exit() value.  This is an issue with Test::More's END block, which
181         wasn't designed to co-exist with a threads environment and forked
182         processes.  Hopefully, that module will be patched in the future, but
183         for now, the warnings are harmless and may be safely ignored.
184

CURRENT AUTHOR AND MAINTAINER

186       Eric Rybski <rybskej@yahoo.com>.  Please send all module inquries to
187       me.
188

ORIGINAL AUTHOR

190       Elizabeth Mattijsen, <liz@dijkmat.nl>.
191
193       Copyright (c)
194        2005-2014 Eric Rybski <rybskej@yahoo.com>,
195        2002-2004 Elizabeth Mattijsen <liz@dijkmat.nl>.  All rights reserved.
196       This program is free software; you can redistribute it and/or modify it
197       under the same terms as Perl itself.
198

SEE ALSO

200       threads::shared, forks, forks::BerkeleyDB::shared.
201
202
203
204perl v5.32.1                      2021-01-27                  forks::shared(3)
Impressum