1 package threads::shared;
8 our @ISA = qw(Exporter);
9 our @EXPORT = qw(share cond_wait cond_broadcast cond_signal _refcnt _id _thrcnt);
10 our $VERSION = '0.90';
12 if ($threads::threads) {
13 *cond_wait = \&cond_wait_enabled;
14 *cond_signal = \&cond_signal_enabled;
15 *cond_broadcast = \&cond_broadcast_enabled;
17 XSLoader::load('threads::shared',$VERSION);
20 *share = \&share_disabled;
21 *cond_wait = \&cond_wait_disabled;
22 *cond_signal = \&cond_signal_disabled;
23 *cond_broadcast = \&cond_broadcast_disabled;
27 sub cond_wait_disabled { return @_ };
28 sub cond_signal_disabled { return @_};
29 sub cond_broadcast_disabled { return @_};
30 sub share_disabled { return @_}
32 $threads::shared::threads_shared = 1;
35 sub threads::shared::tie::SPLICE
37 die "Splice not implemented for shared arrays";
44 threads::shared - Perl extension for sharing data structures between threads
53 my($scalar, @array, %hash);
58 $hash{bar} = &share({});
63 cond_broadcast(@array);
68 By default, variables are private to each thread, and each newly created
69 thread gets a private copy of each existing variable. This module allows
70 you to share variables across different threads (and pseudoforks on
71 win32). It is used together with the threads module.
75 C<share>, C<lock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
77 Note that if this module is imported when C<threads> has not yet been
78 loaded, then these functions all become no-ops. This makes it possible to
79 write modules that will work in both threaded and non-threaded
88 C<share> takes a value and marks it as shared. You can share a scalar,
89 array, hash, scalar ref, array ref or hash ref. C<share> will return
92 C<share> will traverse up references exactly I<one> level.
93 C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
95 A variable can also be marked as shared at compile time by using the
96 C<shared> attribute: C<my $var : shared>.
98 If you want to share a newly created reference unfortunately you
99 need to use C<&share([])> and C<&share({})> syntax due to problems
100 with Perl's prototyping.
104 C<lock> places a lock on a variable until the lock goes out of scope. If
105 the variable is locked by another thread, the C<lock> call will block until
106 it's available. C<lock> is recursive, so multiple calls to C<lock> are
107 safe -- the variable will remain locked until the outermost lock on the
108 variable goes out of scope.
110 If a container object, such as a hash or array, is locked, all the elements
111 of that container are not locked. For example, if a thread does a C<lock
112 @a>, any other thread doing a C<lock($a[12])> won't block.
114 C<lock> will traverse up references exactly I<one> level.
115 C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
117 Note that you cannot explicitly unlock a variable; you can only wait for
118 the lock to go out of scope. If you need more fine-grained control, see
119 L<threads::shared::semaphore>.
121 =item cond_wait VARIABLE
123 The C<cond_wait> function takes a B<locked> variable as a parameter,
124 unlocks the variable, and blocks until another thread does a C<cond_signal>
125 or C<cond_broadcast> for that same locked variable. The variable that
126 C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
127 If there are multiple threads C<cond_wait>ing on the same variable, all but
128 one will reblock waiting to reacquire the lock on the variable. (So if
129 you're only using C<cond_wait> for synchronisation, give up the lock as
130 soon as possible). The two actions of unlocking the variable and entering
131 the blocked wait state are atomic, The two actions of exiting from the
132 blocked wait state and relocking the variable are not.
134 It is important to note that the variable can be notified even if no
135 thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore
136 important to check the value of the variable and go back to waiting if the
137 requirement is not fulfilled.
139 =item cond_signal VARIABLE
141 The C<cond_signal> function takes a B<locked> variable as a parameter and
142 unblocks one thread that's C<cond_wait>ing on that variable. If more than
143 one thread is blocked in a C<cond_wait> on that variable, only one (and
144 which one is indeterminate) will be unblocked.
146 If there are no threads blocked in a C<cond_wait> on the variable, the
147 signal is discarded. By always locking before signaling, you can (with
148 care), avoid signaling before another thread has entered cond_wait().
150 C<cond_signal> will normally generate a warning if you attempt to use it
151 on an unlocked variable. On the rare occasions where doing this may be
152 sensible, you can skip the warning with
154 { no warnings 'threads'; cond_signal($foo) }
156 =item cond_broadcast VARIABLE
158 The C<cond_broadcast> function works similarly to C<cond_signal>.
159 C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
160 in a C<cond_wait> on the locked variable, rather than only one.
166 threads::shared is designed to disable itself silently if threads are
167 not available. If you want access to threads, you must C<use threads>
168 before you C<use threads::shared>. threads will emit a warning if you
169 use it after threads::shared.
173 C<bless> is not supported on shared references. In the current version,
174 C<bless> will only bless the thread local reference and the blessing
175 will not propagate to the other threads. This is expected to be
176 implemented in a future version of Perl.
178 Does not support splice on arrays!
180 Taking references to the elements of shared arrays and hashes does not
181 autovivify the elements, and neither does slicing a shared array/hash
182 over non-existent indices/keys autovivify the elements.
186 Arthur Bergman E<lt>arthur at contiller.seE<gt>
188 threads::shared is released under the same license as Perl
190 Documentation borrowed from the old Thread.pm
194 L<threads>, L<perlthrtut>, L<http://www.perl.com/pub/a/2002/06/11/threads.html>