1forks::shared(3) User Contributed Perl Documentation forks::shared(3)
2
6 forks::shared - drop-in replacement for Perl threads::shared with
7 forks()
8
10 use forks;
11 use forks::shared;
12 my $variable : shared;
14 my @array : shared;
15 my %hash : shared;
16 share( $variable );
18 share( @array );
19 share( %hash );
20 $variable = shared_clone($non_shared_ref_value);
22 $variable = shared_clone({'foo' => [qw/foo bar baz/]});
23 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 bless( $variable, class name );
33 # 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
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 "forks::shared" is currently API compatible with CPAN threads::shared
51 version 1.05.
52
54 "share", "shared_clone", "cond_wait", "cond_timedwait", "cond_signal",
55 "cond_broadcast", "is_shared", "bless"
56 See "EXPORT" in threads::shared for more information.
58
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
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 Automated detection and resolution
72 There are two ways to enable these features: either at import time in a
74 use statement, such as:
75 use forks::shared deadlock => { OPTIONS }
77 or during runtime as a class method call to "set_deadlock_option",
79 like:
80 forks::shared->set_deadlock_option( OPTIONS );
82 #or
83 threads::shared->set_deadlock_option( OPTIONS );
84 where "OPTIONS" may be a combination of any of the following:
86 detect => 1 (enable) or 0 (disable)
88 period => number of seconds between asynchronous polls
89 resolve => 1 (enable) or 0 (disable)
90 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 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 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 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 For example:
118 use forks;
120 use forks::shared
121 deadlock => {detect=> 1, resolve => 1};
122 Manual detection
124 If you wish to check for deadlocks without enabling automated deadlock
126 detection, forks provides an additonal thread object method,
127 $thr->is_deadlocked()
129 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 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 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 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 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 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
162 Some caveats that you need to be aware of.
163 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 If need share CODE refs between threads, the minimum you must do
170 before storing CODE refs is:
171 $Storable::Deparse = $Storable::Eval = 1;
173 See "CODE_REFERENCES" in Storable for detailed information, including
175 potential security risks and ways to protect yourself against them.
176 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
186 Eric Rybski <rybskej@yahoo.com>. Please send all module inquries to
187 me.
188
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
200 threads::shared, forks, forks::BerkeleyDB::shared.
201perl v5.36.0 2022-07-22 forks::shared(3)