Commit | Line | Data |
---|---|---|
b050c948 | 1 | package threads::shared; |
73e09c8f | 2 | |
c46325ea | 3 | use 5.008; |
7473853a | 4 | |
b050c948 AB |
5 | use strict; |
6 | use warnings; | |
73e09c8f | 7 | |
373098c0 JH |
8 | use Scalar::Util qw(reftype refaddr blessed); |
9 | ||
47b62f63 | 10 | our $VERSION = '1.48'; # Please update the pod, too. |
7473853a SP |
11 | my $XS_VERSION = $VERSION; |
12 | $VERSION = eval $VERSION; | |
13 | ||
14 | # Declare that we have been loaded | |
15 | $threads::shared::threads_shared = 1; | |
16 | ||
2d282673 JH |
17 | # Method of complaint about things we can't clone |
18 | $threads::shared::clone_warn = undef; | |
19 | ||
7473853a SP |
20 | # Load the XS code, if applicable |
21 | if ($threads::threads) { | |
22 | require XSLoader; | |
23 | XSLoader::load('threads::shared', $XS_VERSION); | |
24 | ||
25 | *is_shared = \&_id; | |
26 | ||
27 | } else { | |
28 | # String eval is generally evil, but we don't want these subs to | |
29 | # exist at all if 'threads' is not loaded successfully. | |
30 | # Vivifying them conditionally this way saves on average about 4K | |
31 | # of memory per thread. | |
32 | eval <<'_MARKER_'; | |
33 | sub share (\[$@%]) { return $_[0] } | |
34 | sub is_shared (\[$@%]) { undef } | |
35 | sub cond_wait (\[$@%];\[$@%]) { undef } | |
36 | sub cond_timedwait (\[$@%]$;\[$@%]) { undef } | |
37 | sub cond_signal (\[$@%]) { undef } | |
38 | sub cond_broadcast (\[$@%]) { undef } | |
39 | _MARKER_ | |
40 | } | |
41 | ||
42 | ||
43 | ### Export ### | |
44 | ||
45 | sub import | |
46 | { | |
47 | # Exported subroutines | |
48 | my @EXPORT = qw(share is_shared cond_wait cond_timedwait | |
373098c0 | 49 | cond_signal cond_broadcast shared_clone); |
5c360ac5 | 50 | if ($threads::threads) { |
7473853a | 51 | push(@EXPORT, 'bless'); |
5c360ac5 | 52 | } |
7473853a SP |
53 | |
54 | # Export subroutine names | |
55 | my $caller = caller(); | |
56 | foreach my $sym (@EXPORT) { | |
57 | no strict 'refs'; | |
58 | *{$caller.'::'.$sym} = \&{$sym}; | |
df5c998e EM |
59 | } |
60 | } | |
b050c948 | 61 | |
7473853a | 62 | |
373098c0 JH |
63 | # Predeclarations for internal functions |
64 | my ($make_shared); | |
65 | ||
66 | ||
7473853a | 67 | ### Methods, etc. ### |
dab065ea | 68 | |
6b85e4fe NIS |
69 | sub threads::shared::tie::SPLICE |
70 | { | |
7473853a SP |
71 | require Carp; |
72 | Carp::croak('Splice not implemented for shared arrays'); | |
6b85e4fe NIS |
73 | } |
74 | ||
373098c0 JH |
75 | |
76 | # Create a thread-shared clone of a complex data structure or object | |
77 | sub shared_clone | |
78 | { | |
79 | if (@_ != 1) { | |
80 | require Carp; | |
81 | Carp::croak('Usage: shared_clone(REF)'); | |
82 | } | |
83 | ||
84 | return $make_shared->(shift, {}); | |
85 | } | |
86 | ||
87 | ||
88 | ### Internal Functions ### | |
89 | ||
90 | # Used by shared_clone() to recursively clone | |
91 | # a complex data structure or object | |
92 | $make_shared = sub { | |
93 | my ($item, $cloned) = @_; | |
94 | ||
95 | # Just return the item if: | |
96 | # 1. Not a ref; | |
97 | # 2. Already shared; or | |
98 | # 3. Not running 'threads'. | |
99 | return $item if (! ref($item) || is_shared($item) || ! $threads::threads); | |
100 | ||
101 | # Check for previously cloned references | |
102 | # (this takes care of circular refs as well) | |
103 | my $addr = refaddr($item); | |
104 | if (exists($cloned->{$addr})) { | |
105 | # Return the already existing clone | |
106 | return $cloned->{$addr}; | |
107 | } | |
108 | ||
109 | # Make copies of array, hash and scalar refs and refs of refs | |
110 | my $copy; | |
111 | my $ref_type = reftype($item); | |
112 | ||
113 | # Copy an array ref | |
114 | if ($ref_type eq 'ARRAY') { | |
115 | # Make empty shared array ref | |
116 | $copy = &share([]); | |
117 | # Add to clone checking hash | |
118 | $cloned->{$addr} = $copy; | |
119 | # Recursively copy and add contents | |
120 | push(@$copy, map { $make_shared->($_, $cloned) } @$item); | |
121 | } | |
122 | ||
123 | # Copy a hash ref | |
124 | elsif ($ref_type eq 'HASH') { | |
125 | # Make empty shared hash ref | |
126 | $copy = &share({}); | |
127 | # Add to clone checking hash | |
128 | $cloned->{$addr} = $copy; | |
129 | # Recursively copy and add contents | |
130 | foreach my $key (keys(%{$item})) { | |
131 | $copy->{$key} = $make_shared->($item->{$key}, $cloned); | |
132 | } | |
133 | } | |
134 | ||
135 | # Copy a scalar ref | |
136 | elsif ($ref_type eq 'SCALAR') { | |
137 | $copy = \do{ my $scalar = $$item; }; | |
138 | share($copy); | |
373098c0 JH |
139 | # Add to clone checking hash |
140 | $cloned->{$addr} = $copy; | |
141 | } | |
142 | ||
143 | # Copy of a ref of a ref | |
144 | elsif ($ref_type eq 'REF') { | |
145 | # Special handling for $x = \$x | |
146 | if ($addr == refaddr($$item)) { | |
147 | $copy = \$copy; | |
148 | share($copy); | |
149 | $cloned->{$addr} = $copy; | |
150 | } else { | |
151 | my $tmp; | |
152 | $copy = \$tmp; | |
153 | share($copy); | |
154 | # Add to clone checking hash | |
155 | $cloned->{$addr} = $copy; | |
156 | # Recursively copy and add contents | |
157 | $tmp = $make_shared->($$item, $cloned); | |
158 | } | |
159 | ||
160 | } else { | |
161 | require Carp; | |
2d282673 JH |
162 | if (! defined($threads::shared::clone_warn)) { |
163 | Carp::croak("Unsupported ref type: ", $ref_type); | |
164 | } elsif ($threads::shared::clone_warn) { | |
165 | Carp::carp("Unsupported ref type: ", $ref_type); | |
166 | } | |
167 | return undef; | |
373098c0 JH |
168 | } |
169 | ||
170 | # If input item is an object, then bless the copy into the same class | |
171 | if (my $class = blessed($item)) { | |
172 | bless($copy, $class); | |
173 | } | |
174 | ||
175 | # Clone READONLY flag | |
a469502f RGS |
176 | if ($ref_type eq 'SCALAR') { |
177 | if (Internals::SvREADONLY($$item)) { | |
178 | Internals::SvREADONLY($$copy, 1) if ($] >= 5.008003); | |
179 | } | |
180 | } | |
373098c0 | 181 | if (Internals::SvREADONLY($item)) { |
a469502f | 182 | Internals::SvREADONLY($copy, 1) if ($] >= 5.008003); |
373098c0 JH |
183 | } |
184 | ||
185 | return $copy; | |
186 | }; | |
187 | ||
7473853a SP |
188 | 1; |
189 | ||
b050c948 AB |
190 | __END__ |
191 | ||
192 | =head1 NAME | |
193 | ||
194 | threads::shared - Perl extension for sharing data structures between threads | |
195 | ||
7473853a SP |
196 | =head1 VERSION |
197 | ||
47b62f63 | 198 | This document describes threads::shared version 1.48 |
7473853a | 199 | |
b050c948 AB |
200 | =head1 SYNOPSIS |
201 | ||
73e09c8f | 202 | use threads; |
b050c948 AB |
203 | use threads::shared; |
204 | ||
7473853a | 205 | my $var :shared; |
373098c0 JH |
206 | my %hsh :shared; |
207 | my @ary :shared; | |
38875929 | 208 | |
3b29be8d | 209 | my ($scalar, @array, %hash); |
4cab98c0 SG |
210 | share($scalar); |
211 | share(@array); | |
aaf3876d | 212 | share(%hash); |
373098c0 JH |
213 | |
214 | $var = $scalar_value; | |
215 | $var = $shared_ref_value; | |
216 | $var = shared_clone($non_shared_ref_value); | |
217 | $var = shared_clone({'foo' => [qw/foo bar baz/]}); | |
218 | ||
219 | $hsh{'foo'} = $scalar_value; | |
220 | $hsh{'bar'} = $shared_ref_value; | |
221 | $hsh{'baz'} = shared_clone($non_shared_ref_value); | |
222 | $hsh{'quz'} = shared_clone([1..3]); | |
223 | ||
224 | $ary[0] = $scalar_value; | |
225 | $ary[1] = $shared_ref_value; | |
226 | $ary[2] = shared_clone($non_shared_ref_value); | |
227 | $ary[3] = shared_clone([ {}, [] ]); | |
b050c948 | 228 | |
38875929 DM |
229 | { lock(%hash); ... } |
230 | ||
b050c948 | 231 | cond_wait($scalar); |
a0e036c1 | 232 | cond_timedwait($scalar, time() + 30); |
515f0976 AB |
233 | cond_broadcast(@array); |
234 | cond_signal(%hash); | |
b050c948 | 235 | |
7473853a | 236 | my $lockvar :shared; |
a0e036c1 MP |
237 | # condition var != lock var |
238 | cond_wait($var, $lockvar); | |
239 | cond_timedwait($var, time()+30, $lockvar); | |
240 | ||
b050c948 AB |
241 | =head1 DESCRIPTION |
242 | ||
38875929 | 243 | By default, variables are private to each thread, and each newly created |
7473853a | 244 | thread gets a private copy of each existing variable. This module allows you |
373098c0 JH |
245 | to share variables across different threads (and pseudo-forks on Win32). It |
246 | is used together with the L<threads> module. | |
247 | ||
248 | This module supports the sharing of the following data types only: scalars | |
249 | and scalar refs, arrays and array refs, and hashes and hash refs. | |
b050c948 | 250 | |
515f0976 | 251 | =head1 EXPORT |
b050c948 | 252 | |
373098c0 JH |
253 | The following functions are exported by this module: C<share>, |
254 | C<shared_clone>, C<is_shared>, C<cond_wait>, C<cond_timedwait>, C<cond_signal> | |
255 | and C<cond_broadcast> | |
515f0976 | 256 | |
7473853a SP |
257 | Note that if this module is imported when L<threads> has not yet been loaded, |
258 | then these functions all become no-ops. This makes it possible to write | |
259 | modules that will work in both threaded and non-threaded environments. | |
e67b86b3 | 260 | |
515f0976 AB |
261 | =head1 FUNCTIONS |
262 | ||
263 | =over 4 | |
264 | ||
265 | =item share VARIABLE | |
266 | ||
373098c0 JH |
267 | C<share> takes a variable and marks it as shared: |
268 | ||
269 | my ($scalar, @array, %hash); | |
270 | share($scalar); | |
271 | share(@array); | |
272 | share(%hash); | |
273 | ||
274 | C<share> will return the shared rvalue, but always as a reference. | |
515f0976 | 275 | |
373098c0 JH |
276 | Variables can also be marked as shared at compile time by using the |
277 | C<:shared> attribute: | |
38875929 | 278 | |
373098c0 | 279 | my ($var, %hash, @array) :shared; |
caf25f3b | 280 | |
373098c0 JH |
281 | Shared variables can only store scalars, refs of shared variables, or |
282 | refs of shared data (discussed in next section): | |
7473853a | 283 | |
373098c0 JH |
284 | my ($var, %hash, @array) :shared; |
285 | my $bork; | |
286 | ||
287 | # Storing scalars | |
288 | $var = 1; | |
289 | $hash{'foo'} = 'bar'; | |
290 | $array[0] = 1.5; | |
291 | ||
292 | # Storing shared refs | |
293 | $var = \%hash; | |
294 | $hash{'ary'} = \@array; | |
295 | $array[1] = \$var; | |
296 | ||
297 | # The following are errors: | |
298 | # $var = \$bork; # ref of non-shared variable | |
299 | # $hash{'bork'} = []; # non-shared array ref | |
300 | # push(@array, { 'x' => 1 }); # non-shared hash ref | |
7473853a | 301 | |
373098c0 | 302 | =item shared_clone REF |
ca5ff8b2 | 303 | |
373098c0 | 304 | C<shared_clone> takes a reference, and returns a shared version of its |
2e58fc35 | 305 | argument, performing a deep copy on any non-shared elements. Any shared |
373098c0 JH |
306 | elements in the argument are used as is (i.e., they are not cloned). |
307 | ||
308 | my $cpy = shared_clone({'foo' => [qw/foo bar baz/]}); | |
309 | ||
310 | Object status (i.e., the class an object is blessed into) is also cloned. | |
311 | ||
312 | my $obj = {'foo' => [qw/foo bar baz/]}; | |
313 | bless($obj, 'Foo'); | |
314 | my $cpy = shared_clone($obj); | |
315 | print(ref($cpy), "\n"); # Outputs 'Foo' | |
316 | ||
317 | For cloning empty array or hash refs, the following may also be used: | |
318 | ||
2e58fc35 JH |
319 | $var = &share([]); # Same as $var = shared_clone([]); |
320 | $var = &share({}); # Same as $var = shared_clone({}); | |
ca5ff8b2 | 321 | |
2d282673 JH |
322 | Not all Perl data types can be cloned (e.g., globs, code refs). By default, |
323 | C<shared_clone> will L<croak|Carp> if it encounters such items. To change | |
324 | this behaviour to a warning, then set the following: | |
325 | ||
326 | $threads::shared::clone_warn = 1; | |
327 | ||
328 | In this case, C<undef> will be substituted for the item to be cloned. If | |
329 | set to zero: | |
330 | ||
331 | $threads::shared::clone_warn = 0; | |
332 | ||
333 | then the C<undef> substitution will be performed silently. | |
334 | ||
7473853a SP |
335 | =item is_shared VARIABLE |
336 | ||
337 | C<is_shared> checks if the specified variable is shared or not. If shared, | |
338 | returns the variable's internal ID (similar to | |
510990bb | 339 | C<refaddr()> (see L<Scalar::Util>). Otherwise, returns C<undef>. |
7473853a SP |
340 | |
341 | if (is_shared($var)) { | |
342 | print("\$var is shared\n"); | |
343 | } else { | |
344 | print("\$var is not shared\n"); | |
345 | } | |
ca5ff8b2 | 346 | |
c6cab44f JH |
347 | When used on an element of an array or hash, C<is_shared> checks if the |
348 | specified element belongs to a shared array or hash. (It does not check | |
349 | the contents of that element.) | |
350 | ||
351 | my %hash :shared; | |
352 | if (is_shared(%hash)) { | |
353 | print("\%hash is shared\n"); | |
354 | } | |
355 | ||
356 | $hash{'elem'} = 1; | |
357 | if (is_shared($hash{'elem'})) { | |
358 | print("\$hash{'elem'} is in a shared hash\n"); | |
359 | } | |
360 | ||
515f0976 AB |
361 | =item lock VARIABLE |
362 | ||
c6cab44f JH |
363 | C<lock> places a B<advisory> lock on a variable until the lock goes out of |
364 | scope. If the variable is locked by another thread, the C<lock> call will | |
365 | block until it's available. Multiple calls to C<lock> by the same thread from | |
366 | within dynamically nested scopes are safe -- the variable will remain locked | |
367 | until the outermost lock on the variable goes out of scope. | |
7473853a | 368 | |
c6cab44f | 369 | C<lock> follows references exactly I<one> level: |
515f0976 | 370 | |
c6cab44f JH |
371 | my %hash :shared; |
372 | my $ref = \%hash; | |
373 | lock($ref); # This is equivalent to lock(%hash) | |
515f0976 | 374 | |
7473853a SP |
375 | Note that you cannot explicitly unlock a variable; you can only wait for the |
376 | lock to go out of scope. This is most easily accomplished by locking the | |
377 | variable inside a block. | |
515f0976 | 378 | |
7473853a SP |
379 | my $var :shared; |
380 | { | |
381 | lock($var); | |
382 | # $var is locked from here to the end of the block | |
383 | ... | |
384 | } | |
385 | # $var is now unlocked | |
386 | ||
c6cab44f JH |
387 | As locks are advisory, they do not prevent data access or modification by |
388 | another thread that does not itself attempt to obtain a lock on the variable. | |
389 | ||
390 | You cannot lock the individual elements of a container variable: | |
391 | ||
392 | my %hash :shared; | |
393 | $hash{'foo'} = 'bar'; | |
394 | #lock($hash{'foo'}); # Error | |
395 | lock(%hash); # Works | |
396 | ||
7473853a SP |
397 | If you need more fine-grained control over shared variable access, see |
398 | L<Thread::Semaphore>. | |
515f0976 AB |
399 | |
400 | =item cond_wait VARIABLE | |
401 | ||
a0e036c1 MP |
402 | =item cond_wait CONDVAR, LOCKVAR |
403 | ||
7473853a SP |
404 | The C<cond_wait> function takes a B<locked> variable as a parameter, unlocks |
405 | the variable, and blocks until another thread does a C<cond_signal> or | |
406 | C<cond_broadcast> for that same locked variable. The variable that | |
2d282673 | 407 | C<cond_wait> blocked on is re-locked after the C<cond_wait> is satisfied. If |
7473853a | 408 | there are multiple threads C<cond_wait>ing on the same variable, all but one |
e706d92e FC |
409 | will re-block waiting to reacquire the |
410 | lock on the variable. (So if you're only | |
2d282673 | 411 | using C<cond_wait> for synchronization, give up the lock as soon as possible). |
7473853a SP |
412 | The two actions of unlocking the variable and entering the blocked wait state |
413 | are atomic, the two actions of exiting from the blocked wait state and | |
7c8caac0 | 414 | re-locking the variable are not. |
7473853a SP |
415 | |
416 | In its second form, C<cond_wait> takes a shared, B<unlocked> variable followed | |
417 | by a shared, B<locked> variable. The second variable is unlocked and thread | |
418 | execution suspended until another thread signals the first variable. | |
419 | ||
420 | It is important to note that the variable can be notified even if no thread | |
421 | C<cond_signal> or C<cond_broadcast> on the variable. It is therefore | |
422 | important to check the value of the variable and go back to waiting if the | |
423 | requirement is not fulfilled. For example, to pause until a shared counter | |
424 | drops to zero: | |
425 | ||
63790022 | 426 | { lock($counter); cond_wait($counter) until $counter == 0; } |
a0e036c1 MP |
427 | |
428 | =item cond_timedwait VARIABLE, ABS_TIMEOUT | |
429 | ||
430 | =item cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR | |
431 | ||
7473853a | 432 | In its two-argument form, C<cond_timedwait> takes a B<locked> variable and an |
2d282673 JH |
433 | absolute timeout in I<epoch> seconds (see L<time() in perlfunc|perlfunc/time> |
434 | for more) as parameters, unlocks the variable, and blocks until the | |
7473853a SP |
435 | timeout is reached or another thread signals the variable. A false value is |
436 | returned if the timeout is reached, and a true value otherwise. In either | |
437 | case, the variable is re-locked upon return. | |
a0e036c1 | 438 | |
7473853a SP |
439 | Like C<cond_wait>, this function may take a shared, B<locked> variable as an |
440 | additional parameter; in this case the first parameter is an B<unlocked> | |
441 | condition variable protected by a distinct lock variable. | |
a0e036c1 | 442 | |
7473853a SP |
443 | Again like C<cond_wait>, waking up and reacquiring the lock are not atomic, |
444 | and you should always check your desired condition after this function | |
445 | returns. Since the timeout is an absolute value, however, it does not have to | |
446 | be recalculated with each pass: | |
a0e036c1 | 447 | |
7473853a SP |
448 | lock($var); |
449 | my $abs = time() + 15; | |
450 | until ($ok = desired_condition($var)) { | |
a0e036c1 | 451 | last if !cond_timedwait($var, $abs); |
7473853a SP |
452 | } |
453 | # we got it if $ok, otherwise we timed out! | |
515f0976 AB |
454 | |
455 | =item cond_signal VARIABLE | |
456 | ||
7473853a | 457 | The C<cond_signal> function takes a B<locked> variable as a parameter and |
e706d92e FC |
458 | unblocks one thread that's C<cond_wait>ing |
459 | on that variable. If more than one | |
7473853a SP |
460 | thread is blocked in a C<cond_wait> on that variable, only one (and which one |
461 | is indeterminate) will be unblocked. | |
515f0976 | 462 | |
7473853a | 463 | If there are no threads blocked in a C<cond_wait> on the variable, the signal |
e706d92e FC |
464 | is discarded. By always locking before |
465 | signaling, you can (with care), avoid | |
7473853a | 466 | signaling before another thread has entered cond_wait(). |
38875929 | 467 | |
7473853a | 468 | C<cond_signal> will normally generate a warning if you attempt to use it on an |
e706d92e FC |
469 | unlocked variable. On the rare occasions |
470 | where doing this may be sensible, you | |
ba2940ce | 471 | can suppress the warning with: |
38875929 | 472 | |
7473853a | 473 | { no warnings 'threads'; cond_signal($foo); } |
515f0976 AB |
474 | |
475 | =item cond_broadcast VARIABLE | |
476 | ||
477 | The C<cond_broadcast> function works similarly to C<cond_signal>. | |
7473853a SP |
478 | C<cond_broadcast>, though, will unblock B<all> the threads that are blocked in |
479 | a C<cond_wait> on the locked variable, rather than only one. | |
b050c948 | 480 | |
4cab98c0 | 481 | =back |
dab065ea | 482 | |
7473853a SP |
483 | =head1 OBJECTS |
484 | ||
485 | L<threads::shared> exports a version of L<bless()|perlfunc/"bless REF"> that | |
2b936299 | 486 | works on shared objects such that I<blessings> propagate across threads. |
7473853a | 487 | |
373098c0 JH |
488 | # Create a shared 'Foo' object |
489 | my $foo :shared = shared_clone({}); | |
490 | bless($foo, 'Foo'); | |
7473853a | 491 | |
373098c0 JH |
492 | # Create a shared 'Bar' object |
493 | my $bar :shared = shared_clone({}); | |
494 | bless($bar, 'Bar'); | |
7473853a SP |
495 | |
496 | # Put 'bar' inside 'foo' | |
497 | $foo->{'bar'} = $bar; | |
498 | ||
499 | # Rebless the objects via a thread | |
500 | threads->create(sub { | |
501 | # Rebless the outer object | |
373098c0 | 502 | bless($foo, 'Yin'); |
7473853a SP |
503 | |
504 | # Cannot directly rebless the inner object | |
373098c0 | 505 | #bless($foo->{'bar'}, 'Yang'); |
7473853a SP |
506 | |
507 | # Retrieve and rebless the inner object | |
508 | my $obj = $foo->{'bar'}; | |
373098c0 | 509 | bless($obj, 'Yang'); |
7473853a SP |
510 | $foo->{'bar'} = $obj; |
511 | ||
512 | })->join(); | |
513 | ||
373098c0 JH |
514 | print(ref($foo), "\n"); # Prints 'Yin' |
515 | print(ref($foo->{'bar'}), "\n"); # Prints 'Yang' | |
516 | print(ref($bar), "\n"); # Also prints 'Yang' | |
7473853a | 517 | |
dab065ea AB |
518 | =head1 NOTES |
519 | ||
33d16ee7 JH |
520 | L<threads::shared> is designed to disable itself silently if threads are not |
521 | available. This allows you to write modules and packages that can be used | |
522 | in both threaded and non-threaded applications. | |
523 | ||
524 | If you want access to threads, you must C<use threads> before you | |
7473853a SP |
525 | C<use threads::shared>. L<threads> will emit a warning if you use it after |
526 | L<threads::shared>. | |
dab065ea | 527 | |
fd013656 FC |
528 | =head1 WARNINGS |
529 | ||
530 | =over 4 | |
531 | ||
532 | =item cond_broadcast() called on unlocked variable | |
533 | ||
fd013656 FC |
534 | =item cond_signal() called on unlocked variable |
535 | ||
7fb64fce | 536 | See L</"cond_signal VARIABLE">, above. |
fd013656 FC |
537 | |
538 | =back | |
539 | ||
7473853a | 540 | =head1 BUGS AND LIMITATIONS |
b050c948 | 541 | |
7473853a SP |
542 | When C<share> is used on arrays, hashes, array refs or hash refs, any data |
543 | they contain will be lost. | |
515f0976 | 544 | |
7473853a SP |
545 | my @arr = qw(foo bar baz); |
546 | share(@arr); | |
547 | # @arr is now empty (i.e., == ()); | |
b050c948 | 548 | |
7473853a SP |
549 | # Create a 'foo' object |
550 | my $foo = { 'data' => 99 }; | |
551 | bless($foo, 'foo'); | |
58122748 | 552 | |
7473853a SP |
553 | # Share the object |
554 | share($foo); # Contents are now wiped out | |
555 | print("ERROR: \$foo is empty\n") | |
556 | if (! exists($foo->{'data'})); | |
3d32476b | 557 | |
7473853a SP |
558 | Therefore, populate such variables B<after> declaring them as shared. (Scalar |
559 | and scalar refs are not affected by this problem.) | |
560 | ||
561 | It is often not wise to share an object unless the class itself has been | |
2b936299 RGS |
562 | written to support sharing. For example, an object's destructor may get |
563 | called multiple times, once for each thread's scope exit. Another danger is | |
564 | that the contents of hash-based objects will be lost due to the above | |
565 | mentioned limitation. See F<examples/class.pl> (in the CPAN distribution of | |
566 | this module) for how to create a class that supports object sharing. | |
b050c948 | 567 | |
7d585d2f FC |
568 | Destructors may not be called on objects if those objects still exist at |
569 | global destruction time. If the destructors must be called, make sure | |
570 | there are no circular references and that nothing is referencing the | |
571 | objects, before the program ends. | |
b9e224a7 | 572 | |
1a3f0f1d S |
573 | Does not support C<splice> on arrays. Does not support explicitly changing |
574 | array lengths via $#array -- use C<push> and C<pop> instead. | |
b050c948 | 575 | |
7473853a SP |
576 | Taking references to the elements of shared arrays and hashes does not |
577 | autovivify the elements, and neither does slicing a shared array/hash over | |
578 | non-existent indices/keys autovivify the elements. | |
579 | ||
c6cab44f JH |
580 | C<share()> allows you to C<< share($hashref->{key}) >> and |
581 | C<< share($arrayref->[idx]) >> without giving any error message. But the | |
582 | C<< $hashref->{key} >> or C<< $arrayref->[idx] >> is B<not> shared, causing | |
583 | the error "lock can only be used on shared values" to occur when you attempt | |
033de87f | 584 | to C<< lock($hashref->{key}) >> or C<< lock($arrayref->[idx]) >> in another |
c6cab44f | 585 | thread. |
b050c948 | 586 | |
510990bb | 587 | Using C<refaddr()> is unreliable for testing |
f6d55995 | 588 | whether or not two shared references are equivalent (e.g., when testing for |
1357b38e | 589 | circular references). Use L<is_shared()|/"is_shared VARIABLE">, instead: |
f6d55995 JH |
590 | |
591 | use threads; | |
592 | use threads::shared; | |
593 | use Scalar::Util qw(refaddr); | |
594 | ||
595 | # If ref is shared, use threads::shared's internal ID. | |
596 | # Otherwise, use refaddr(). | |
597 | my $addr1 = is_shared($ref1) || refaddr($ref1); | |
598 | my $addr2 = is_shared($ref2) || refaddr($ref2); | |
599 | ||
600 | if ($addr1 == $addr2) { | |
601 | # The refs are equivalent | |
602 | } | |
603 | ||
2e58fc35 JH |
604 | L<each()|perlfunc/"each HASH"> does not work properly on shared references |
605 | embedded in shared structures. For example: | |
606 | ||
607 | my %foo :shared; | |
608 | $foo{'bar'} = shared_clone({'a'=>'x', 'b'=>'y', 'c'=>'z'}); | |
609 | ||
610 | while (my ($key, $val) = each(%{$foo{'bar'}})) { | |
611 | ... | |
612 | } | |
613 | ||
614 | Either of the following will work instead: | |
615 | ||
616 | my $ref = $foo{'bar'}; | |
617 | while (my ($key, $val) = each(%{$ref})) { | |
618 | ... | |
619 | } | |
620 | ||
621 | foreach my $key (keys(%{$foo{'bar'}})) { | |
622 | my $val = $foo{'bar'}{$key}; | |
623 | ... | |
624 | } | |
625 | ||
510990bb FC |
626 | This module supports dual-valued variables created using C<dualvar()> from |
627 | L<Scalar::Util>. However, while C<$!> acts | |
033de87f JH |
628 | like a dualvar, it is implemented as a tied SV. To propagate its value, use |
629 | the follow construct, if needed: | |
630 | ||
631 | my $errno :shared = dualvar($!,$!); | |
632 | ||
7473853a | 633 | View existing bug reports at, and submit any new bugs, problems, patches, etc. |
794f4697 | 634 | to: L<http://rt.cpan.org/Public/Dist/Display.html?Name=threads-shared> |
515f0976 | 635 | |
b050c948 AB |
636 | =head1 SEE ALSO |
637 | ||
7473853a SP |
638 | L<threads::shared> Discussion Forum on CPAN: |
639 | L<http://www.cpanforum.com/dist/threads-shared> | |
640 | ||
7473853a SP |
641 | L<threads>, L<perlthrtut> |
642 | ||
643 | L<http://www.perl.com/pub/a/2002/06/11/threads.html> and | |
644 | L<http://www.perl.com/pub/a/2002/09/04/threads.html> | |
645 | ||
646 | Perl threads mailing list: | |
a2770437 | 647 | L<http://lists.perl.org/list/ithreads.html> |
7473853a SP |
648 | |
649 | =head1 AUTHOR | |
650 | ||
651 | Artur Bergman E<lt>sky AT crucially DOT netE<gt> | |
652 | ||
7473853a SP |
653 | Documentation borrowed from the old Thread.pm. |
654 | ||
655 | CPAN version produced by Jerry D. Hedden E<lt>jdhedden AT cpan DOT orgE<gt>. | |
b050c948 | 656 | |
6c791b15 JH |
657 | =head1 LICENSE |
658 | ||
659 | threads::shared is released under the same license as Perl. | |
660 | ||
b050c948 | 661 | =cut |