← Index
Performance Profile   « block view • line view • sub view »
For /wise/base/deliv/dev/bin/getfix
  Run on Thu May 20 15:30:03 2010
Reported on Thu May 20 16:25:40 2010

File/opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/threads/shared.pm
Statements Executed29
Total Time0.001098 seconds

Subroutines — ordered by exclusive time
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
1114.1e-54.1e-5threads::shared::import
00000threads::shared::BEGIN
00000threads::shared::tie::SPLICE

LineStmts.Exclusive
Time		Avg.Code
1package threads::shared;
2
336.8e-52.3e-5use 5.008;
4
532.6e-58.7e-6use strict;
# spent 8µs making 1 call to strict::import
630.000196.3e-5use warnings;
# spent 24µs making 1 call to warnings::import
7
811.0e-61.0e-6our $VERSION = '1.14';
911.0e-61.0e-6my $XS_VERSION = $VERSION;
1013.2e-53.2e-5$VERSION = eval $VERSION;
11
12# Declare that we have been loaded
1311.0e-61.0e-6$threads::shared::threads_shared = 1;
14
15# Load the XS code, if applicable
1612.0e-62.0e-6if ($threads::threads) {
17 require XSLoader;
18 XSLoader::load('threads::shared', $XS_VERSION);
19
20 *is_shared = \&_id;
21
22} else {
23 # String eval is generally evil, but we don't want these subs to
24 # exist at all if 'threads' is not loaded successfully.
25 # Vivifying them conditionally this way saves on average about 4K
26 # of memory per thread.
2710.000130.00013 eval <<'_MARKER_';
28 sub share (\[$@%]) { return $_[0] }
29 sub is_shared (\[$@%]) { undef }
30 sub cond_wait (\[$@%];\[$@%]) { undef }
31 sub cond_timedwait (\[$@%]$;\[$@%]) { undef }
32 sub cond_signal (\[$@%]) { undef }
33 sub cond_broadcast (\[$@%]) { undef }
34_MARKER_
35}
36
37
38### Export ###
39
40sub import
41
# spent 41µs within threads::shared::import which was called # once (41µs+0) at line 6 of /wise/base/deliv/dev/lib/perl/WISE/Spawn.pm
{
42 # Exported subroutines
4312.0e-62.0e-6 my @EXPORT = qw(share is_shared cond_wait cond_timedwait
44 cond_signal cond_broadcast);
4511.0e-61.0e-6 if ($threads::threads) {
46 push(@EXPORT, 'bless');
47 }
48
49 # Export subroutine names
5011.0e-61.0e-6 my $caller = caller();
5113.0e-63.0e-6 foreach my $sym (@EXPORT) {
5230.000600.00020 no strict 'refs';
# spent 29µs making 1 call to strict::unimport
5362.8e-54.7e-6 *{$caller.'::'.$sym} = \&{$sym};
54 }
55}
56
57
58### Methods, etc. ###
59
60sub threads::shared::tie::SPLICE
61{
62 require Carp;
63 Carp::croak('Splice not implemented for shared arrays');
64}
65
6619.0e-69.0e-61;
67
68__END__
69
70=head1 NAME
71
72threads::shared - Perl extension for sharing data structures between threads
73
74=head1 VERSION
75
76This document describes threads::shared version 1.14
77
78=head1 SYNOPSIS
79
80 use threads;
81 use threads::shared;
82
83 my $var :shared;
84 $var = $scalar_value;
85 $var = $shared_ref_value;
86 $var = share($simple_unshared_ref_value);
87
88 my ($scalar, @array, %hash);
89 share($scalar);
90 share(@array);
91 share(%hash);
92 my $bar = &share([]);
93 $hash{bar} = &share({});
94
95 { lock(%hash); ... }
96
97 cond_wait($scalar);
98 cond_timedwait($scalar, time() + 30);
99 cond_broadcast(@array);
100 cond_signal(%hash);
101
102 my $lockvar :shared;
103 # condition var != lock var
104 cond_wait($var, $lockvar);
105 cond_timedwait($var, time()+30, $lockvar);
106
107=head1 DESCRIPTION
108
109By default, variables are private to each thread, and each newly created
110thread gets a private copy of each existing variable. This module allows you
111to share variables across different threads (and pseudo-forks on Win32). It is
112used together with the L<threads> module.
113
114=head1 EXPORT
115
116C<share>, C<cond_wait>, C<cond_timedwait>, C<cond_signal>, C<cond_broadcast>,
117C<is_shared>
118
119Note that if this module is imported when L<threads> has not yet been loaded,
120then these functions all become no-ops. This makes it possible to write
121modules that will work in both threaded and non-threaded environments.
122
123=head1 FUNCTIONS
124
125=over 4
126
127=item share VARIABLE
128
129C<share> takes a value and marks it as shared. You can share a scalar, array,
130hash, scalar ref, array ref, or hash ref. C<share> will return the shared
131rvalue, but always as a reference.
132
133A variable can also be marked as shared at compile time by using the
134C<:shared> attribute: C<my $var :shared;>.
135
136Due to problems with Perl's prototyping, if you want to share a newly created
137reference, you need to use the C<&share([])> and C<&share({})> syntax.
138
139The only values that can be assigned to a shared scalar are other scalar
140values, or shared refs:
141
142 my $var :shared;
143 $var = 1; # ok
144 $var = []; # error
145 $var = &share([]); # ok
146
147C<share> will traverse up references exactly I<one> level. C<share(\$a)> is
148equivalent to C<share($a)>, while C<share(\\$a)> is not. This means that you
149must create nested shared data structures by first creating individual shared
150leaf nodes, and then adding them to a shared hash or array.
151
152 my %hash :shared;
153 $hash{'meaning'} = &share([]);
154 $hash{'meaning'}[0] = &share({});
155 $hash{'meaning'}[0]{'life'} = 42;
156
157=item is_shared VARIABLE
158
159C<is_shared> checks if the specified variable is shared or not. If shared,
160returns the variable's internal ID (similar to
161L<refaddr()|Scalar::Util/"refaddr EXPR">). Otherwise, returns C<undef>.
162
163 if (is_shared($var)) {
164 print("\$var is shared\n");
165 } else {
166 print("\$var is not shared\n");
167 }
168
169=item lock VARIABLE
170
171C<lock> places a lock on a variable until the lock goes out of scope. If the
172variable is locked by another thread, the C<lock> call will block until it's
173available. Multiple calls to C<lock> by the same thread from within
174dynamically nested scopes are safe -- the variable will remain locked until
175the outermost lock on the variable goes out of scope.
176
177Locking a container object, such as a hash or array, doesn't lock the elements
178of that container. For example, if a thread does a C<lock(@a)>, any other
179thread doing a C<lock($a[12])> won't block.
180
181C<lock()> follows references exactly I<one> level. C<lock(\$a)> is equivalent
182to C<lock($a)>, while C<lock(\\$a)> is not.
183
184Note that you cannot explicitly unlock a variable; you can only wait for the
185lock to go out of scope. This is most easily accomplished by locking the
186variable inside a block.
187
188 my $var :shared;
189 {
190 lock($var);
191 # $var is locked from here to the end of the block
192 ...
193 }
194 # $var is now unlocked
195
196If you need more fine-grained control over shared variable access, see
197L<Thread::Semaphore>.
198
199=item cond_wait VARIABLE
200
201=item cond_wait CONDVAR, LOCKVAR
202
203The C<cond_wait> function takes a B<locked> variable as a parameter, unlocks
204the variable, and blocks until another thread does a C<cond_signal> or
205C<cond_broadcast> for that same locked variable. The variable that
206C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied. If
207there are multiple threads C<cond_wait>ing on the same variable, all but one
208will re-block waiting to reacquire the lock on the variable. (So if you're only
209using C<cond_wait> for synchronisation, give up the lock as soon as possible).
210The two actions of unlocking the variable and entering the blocked wait state
211are atomic, the two actions of exiting from the blocked wait state and
212re-locking the variable are not.
213
214In its second form, C<cond_wait> takes a shared, B<unlocked> variable followed
215by a shared, B<locked> variable. The second variable is unlocked and thread
216execution suspended until another thread signals the first variable.
217
218It is important to note that the variable can be notified even if no thread
219C<cond_signal> or C<cond_broadcast> on the variable. It is therefore
220important to check the value of the variable and go back to waiting if the
221requirement is not fulfilled. For example, to pause until a shared counter
222drops to zero:
223
224 { lock($counter); cond_wait($count) until $counter == 0; }
225
226=item cond_timedwait VARIABLE, ABS_TIMEOUT
227
228=item cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR
229
230In its two-argument form, C<cond_timedwait> takes a B<locked> variable and an
231absolute timeout as parameters, unlocks the variable, and blocks until the
232timeout is reached or another thread signals the variable. A false value is
233returned if the timeout is reached, and a true value otherwise. In either
234case, the variable is re-locked upon return.
235
236Like C<cond_wait>, this function may take a shared, B<locked> variable as an
237additional parameter; in this case the first parameter is an B<unlocked>
238condition variable protected by a distinct lock variable.
239
240Again like C<cond_wait>, waking up and reacquiring the lock are not atomic,
241and you should always check your desired condition after this function
242returns. Since the timeout is an absolute value, however, it does not have to
243be recalculated with each pass:
244
245 lock($var);
246 my $abs = time() + 15;
247 until ($ok = desired_condition($var)) {
248 last if !cond_timedwait($var, $abs);
249 }
250 # we got it if $ok, otherwise we timed out!
251
252=item cond_signal VARIABLE
253
254The C<cond_signal> function takes a B<locked> variable as a parameter and
255unblocks one thread that's C<cond_wait>ing on that variable. If more than one
256thread is blocked in a C<cond_wait> on that variable, only one (and which one
257is indeterminate) will be unblocked.
258
259If there are no threads blocked in a C<cond_wait> on the variable, the signal
260is discarded. By always locking before signaling, you can (with care), avoid
261signaling before another thread has entered cond_wait().
262
263C<cond_signal> will normally generate a warning if you attempt to use it on an
264unlocked variable. On the rare occasions where doing this may be sensible, you
265can suppress the warning with:
266
267 { no warnings 'threads'; cond_signal($foo); }
268
269=item cond_broadcast VARIABLE
270
271The C<cond_broadcast> function works similarly to C<cond_signal>.
272C<cond_broadcast>, though, will unblock B<all> the threads that are blocked in
273a C<cond_wait> on the locked variable, rather than only one.
274
275=back
276
277=head1 OBJECTS
278
279L<threads::shared> exports a version of L<bless()|perlfunc/"bless REF"> that
280works on shared objects such that I<blessings> propagate across threads.
281
282 # Create a shared 'foo' object
283 my $foo;
284 share($foo);
285 $foo = &share({});
286 bless($foo, 'foo');
287
288 # Create a shared 'bar' object
289 my $bar;
290 share($bar);
291 $bar = &share({});
292 bless($bar, 'bar');
293
294 # Put 'bar' inside 'foo'
295 $foo->{'bar'} = $bar;
296
297 # Rebless the objects via a thread
298 threads->create(sub {
299 # Rebless the outer object
300 bless($foo, 'yin');
301
302 # Cannot directly rebless the inner object
303 #bless($foo->{'bar'}, 'yang');
304
305 # Retrieve and rebless the inner object
306 my $obj = $foo->{'bar'};
307 bless($obj, 'yang');
308 $foo->{'bar'} = $obj;
309
310 })->join();
311
312 print(ref($foo), "\n"); # Prints 'yin'
313 print(ref($foo->{'bar'}), "\n"); # Prints 'yang'
314 print(ref($bar), "\n"); # Also prints 'yang'
315
316=head1 NOTES
317
318threads::shared is designed to disable itself silently if threads are not
319available. If you want access to threads, you must C<use threads> before you
320C<use threads::shared>. L<threads> will emit a warning if you use it after
321L<threads::shared>.
322
323=head1 BUGS AND LIMITATIONS
324
325When C<share> is used on arrays, hashes, array refs or hash refs, any data
326they contain will be lost.
327
328 my @arr = qw(foo bar baz);
329 share(@arr);
330 # @arr is now empty (i.e., == ());
331
332 # Create a 'foo' object
333 my $foo = { 'data' => 99 };
334 bless($foo, 'foo');
335
336 # Share the object
337 share($foo); # Contents are now wiped out
338 print("ERROR: \$foo is empty\n")
339 if (! exists($foo->{'data'}));
340
341Therefore, populate such variables B<after> declaring them as shared. (Scalar
342and scalar refs are not affected by this problem.)
343
344It is often not wise to share an object unless the class itself has been
345written to support sharing. For example, an object's destructor may get
346called multiple times, once for each thread's scope exit. Another danger is
347that the contents of hash-based objects will be lost due to the above
348mentioned limitation. See F<examples/class.pl> (in the CPAN distribution of
349this module) for how to create a class that supports object sharing.
350
351Does not support C<splice> on arrays!
352
353Taking references to the elements of shared arrays and hashes does not
354autovivify the elements, and neither does slicing a shared array/hash over
355non-existent indices/keys autovivify the elements.
356
357C<share()> allows you to C<< share($hashref->{key}) >> without giving any
358error message. But the C<< $hashref->{key} >> is B<not> shared, causing the
359error "locking can only be used on shared values" to occur when you attempt to
360C<< lock($hasref->{key}) >>.
361
362View existing bug reports at, and submit any new bugs, problems, patches, etc.
363to: L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=threads-shared>
364
365=head1 SEE ALSO
366
367L<threads::shared> Discussion Forum on CPAN:
368L<http://www.cpanforum.com/dist/threads-shared>
369
370Annotated POD for L<threads::shared>:
371L<http://annocpan.org/~JDHEDDEN/threads-shared-1.14/shared.pm>
372
373Source repository:
374L<http://code.google.com/p/threads-shared/>
375
376L<threads>, L<perlthrtut>
377
378L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
379L<http://www.perl.com/pub/a/2002/09/04/threads.html>
380
381Perl threads mailing list:
382L<http://lists.cpan.org/showlist.cgi?name=iThreads>
383
384=head1 AUTHOR
385
386Artur Bergman E<lt>sky AT crucially DOT netE<gt>
387
388threads::shared is released under the same license as Perl.
389
390Documentation borrowed from the old Thread.pm.
391
392CPAN version produced by Jerry D. Hedden E<lt>jdhedden AT cpan DOT orgE<gt>.
393
394=cut

Report produced by the NYTProf 2.07 Perl profiler, developed by Tim Bunce and Adam Kaplan.