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>
83 C<share> takes a value and marks it as shared. You can share a scalar,
84 array, hash, scalar ref, array ref or hash ref. C<share> will return
87 C<share> will traverse up references exactly I<one> level.
88 C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
90 A variable can also be marked as shared at compile time by using the
91 C<shared> attribute: C<my $var : shared>.
93 If you want to share a newly created reference unfortunately you
94 need to use C<&share([])> and C<&share({})> syntax due to problems
95 with Perl's prototyping.
99 C<lock> places a lock on a variable until the lock goes out of scope. If
100 the variable is locked by another thread, the C<lock> call will block until
101 it's available. C<lock> is recursive, so multiple calls to C<lock> are
102 safe -- the variable will remain locked until the outermost lock on the
103 variable goes out of scope.
105 If a container object, such as a hash or array, is locked, all the elements
106 of that container are not locked. For example, if a thread does a C<lock
107 @a>, any other thread doing a C<lock($a[12])> won't block.
109 C<lock> will traverse up references exactly I<one> level.
110 C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
112 Note that you cannot explicitly unlock a variable; you can only wait for
113 the lock to go out of scope. If you need more fine-grained control, see
114 L<threads::shared::semaphore>.
116 =item cond_wait VARIABLE
118 The C<cond_wait> function takes a B<locked> variable as a parameter,
119 unlocks the variable, and blocks until another thread does a C<cond_signal>
120 or C<cond_broadcast> for that same locked variable. The variable that
121 C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
122 If there are multiple threads C<cond_wait>ing on the same variable, all but
123 one will reblock waiting to reacquire the lock on the variable. (So if
124 you're only using C<cond_wait> for synchronisation, give up the lock as
125 soon as possible). The two actions of unlocking the variable and entering
126 the blocked wait state are atomic, The two actions of exiting from the
127 blocked wait state and relocking the variable are not.
129 It is important to note that the variable can be notified even if no
130 thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore
131 important to check the value of the variable and go back to waiting if the
132 requirement is not fulfilled.
134 =item cond_signal VARIABLE
136 The C<cond_signal> function takes a B<locked> variable as a parameter and
137 unblocks one thread that's C<cond_wait>ing on that variable. If more than
138 one thread is blocked in a C<cond_wait> on that variable, only one (and
139 which one is indeterminate) will be unblocked.
141 If there are no threads blocked in a C<cond_wait> on the variable, the
142 signal is discarded. By always locking before signaling, you can (with
143 care), avoid signaling before another thread has entered cond_wait().
145 C<cond_signal> will normally generate a warning if you attempt to use it
146 on an unlocked variable. On the rare occasions where doing this may be
147 sensible, you can skip the warning with
149 { no warnings 'threads'; cond_signal($foo) }
151 =item cond_broadcast VARIABLE
153 The C<cond_broadcast> function works similarly to C<cond_signal>.
154 C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
155 in a C<cond_wait> on the locked variable, rather than only one.
161 threads::shared is designed to disable itself silently if threads are
162 not available. If you want access to threads, you must C<use threads>
163 before you C<use threads::shared>. threads will emit a warning if you
164 use it after threads::shared.
168 C<bless> is not supported on shared references. In the current version,
169 C<bless> will only bless the thread local reference and the blessing
170 will not propagate to the other threads. This is expected to be
171 implemented in a future version of Perl.
173 Does not support splice on arrays!
175 Taking references to the elements of shared arrays and hashes does not
176 autovivify the elements, and neither does slicing a shared array/hash
177 over non-existent indices/keys autovivify the elements.
181 Arthur Bergman E<lt>arthur at contiller.seE<gt>
183 threads::shared is released under the same license as Perl
185 Documentation borrowed from the old Thread.pm
189 L<threads>, L<perlthrtut>, L<http://www.perl.com/pub/a/2002/06/11/threads.html>