Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | package threads::shared; |
2 | ||
3 | use 5.008; | |
4 | use strict; | |
5 | use warnings; | |
6 | BEGIN { | |
7 | require Exporter; | |
8 | our @ISA = qw(Exporter); | |
9 | our @EXPORT = qw(share cond_wait cond_timedwait cond_broadcast cond_signal); | |
10 | our $VERSION = '0.94'; | |
11 | ||
12 | if ($threads::threads) { | |
13 | *cond_wait = \&cond_wait_enabled; | |
14 | *cond_timedwait = \&cond_timedwait_enabled; | |
15 | *cond_signal = \&cond_signal_enabled; | |
16 | *cond_broadcast = \&cond_broadcast_enabled; | |
17 | require XSLoader; | |
18 | XSLoader::load('threads::shared',$VERSION); | |
19 | push @EXPORT,'bless'; | |
20 | } | |
21 | else { | |
22 | ||
23 | # String eval is generally evil, but we don't want these subs to exist at all | |
24 | # if threads are loaded successfully. Vivifying them conditionally this way | |
25 | # saves on average about 4K of memory per thread. | |
26 | ||
27 | eval <<'EOD'; | |
28 | sub cond_wait (\[$@%];\[$@%]) { undef } | |
29 | sub cond_timedwait (\[$@%]$;\[$@%]) { undef } | |
30 | sub cond_signal (\[$@%]) { undef } | |
31 | sub cond_broadcast (\[$@%]) { undef } | |
32 | sub share (\[$@%]) { return $_[0] } | |
33 | EOD | |
34 | } | |
35 | } | |
36 | ||
37 | $threads::shared::threads_shared = 1; | |
38 | ||
39 | sub threads::shared::tie::SPLICE | |
40 | { | |
41 | die "Splice not implemented for shared arrays"; | |
42 | } | |
43 | ||
44 | __END__ | |
45 | ||
46 | =head1 NAME | |
47 | ||
48 | threads::shared - Perl extension for sharing data structures between threads | |
49 | ||
50 | =head1 SYNOPSIS | |
51 | ||
52 | use threads; | |
53 | use threads::shared; | |
54 | ||
55 | my $var : shared; | |
56 | $var = $scalar_value; | |
57 | $var = $shared_ref_value; | |
58 | $var = &share($simple_unshared_ref_value); | |
59 | $var = &share(new Foo); | |
60 | ||
61 | my($scalar, @array, %hash); | |
62 | share($scalar); | |
63 | share(@array); | |
64 | share(%hash); | |
65 | my $bar = &share([]); | |
66 | $hash{bar} = &share({}); | |
67 | ||
68 | { lock(%hash); ... } | |
69 | ||
70 | cond_wait($scalar); | |
71 | cond_timedwait($scalar, time() + 30); | |
72 | cond_broadcast(@array); | |
73 | cond_signal(%hash); | |
74 | ||
75 | my $lockvar : shared; | |
76 | # condition var != lock var | |
77 | cond_wait($var, $lockvar); | |
78 | cond_timedwait($var, time()+30, $lockvar); | |
79 | ||
80 | =head1 DESCRIPTION | |
81 | ||
82 | By default, variables are private to each thread, and each newly created | |
83 | thread gets a private copy of each existing variable. This module allows | |
84 | you to share variables across different threads (and pseudoforks on Win32). | |
85 | It is used together with the threads module. | |
86 | ||
87 | =head1 EXPORT | |
88 | ||
89 | C<share>, C<cond_wait>, C<cond_timedwait>, C<cond_signal>, C<cond_broadcast> | |
90 | ||
91 | Note that if this module is imported when C<threads> has not yet been | |
92 | loaded, then these functions all become no-ops. This makes it possible | |
93 | to write modules that will work in both threaded and non-threaded | |
94 | environments. | |
95 | ||
96 | =head1 FUNCTIONS | |
97 | ||
98 | =over 4 | |
99 | ||
100 | =item share VARIABLE | |
101 | ||
102 | C<share> takes a value and marks it as shared. You can share a scalar, | |
103 | array, hash, scalar ref, array ref or hash ref. C<share> will return | |
104 | the shared rvalue but always as a reference. | |
105 | ||
106 | C<share> will traverse up references exactly I<one> level. | |
107 | C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not. | |
108 | This means that you must create nested shared data structures by first | |
109 | creating individual shared leaf notes, then adding them to a shared hash | |
110 | or array. | |
111 | ||
112 | A variable can also be marked as shared at compile time by using the | |
113 | C<shared> attribute: C<my $var : shared>. | |
114 | ||
115 | If you want to share a newly created reference unfortunately you | |
116 | need to use C<&share([])> and C<&share({})> syntax due to problems | |
117 | with Perl's prototyping. | |
118 | ||
119 | The only values that can be assigned to a shared scalar are other scalar | |
120 | values, or shared refs, eg | |
121 | ||
122 | my $var : shared; | |
123 | $var = 1; # ok | |
124 | $var = &share([]); # ok | |
125 | $var = []; # error | |
126 | $var = A->new; # error | |
127 | $var = &share(A->new); # ok as long as the A object is not nested | |
128 | ||
129 | Note that it is often not wise to share an object unless the class itself | |
130 | has been written to support sharing; for example, an object's destructor | |
131 | may get called multiple times, one for each thread's scope exit. | |
132 | ||
133 | =item lock VARIABLE | |
134 | ||
135 | C<lock> places a lock on a variable until the lock goes out of scope. | |
136 | If the variable is locked by another thread, the C<lock> call will | |
137 | block until it's available. C<lock> is recursive, so multiple calls | |
138 | to C<lock> are safe -- the variable will remain locked until the | |
139 | outermost lock on the variable goes out of scope. | |
140 | ||
141 | If a container object, such as a hash or array, is locked, all the | |
142 | elements of that container are not locked. For example, if a thread | |
143 | does a C<lock @a>, any other thread doing a C<lock($a[12])> won't block. | |
144 | ||
145 | C<lock> will traverse up references exactly I<one> level. | |
146 | C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not. | |
147 | ||
148 | Note that you cannot explicitly unlock a variable; you can only wait | |
149 | for the lock to go out of scope. If you need more fine-grained | |
150 | control, see L<Thread::Semaphore>. | |
151 | ||
152 | =item cond_wait VARIABLE | |
153 | ||
154 | =item cond_wait CONDVAR, LOCKVAR | |
155 | ||
156 | The C<cond_wait> function takes a B<locked> variable as a parameter, | |
157 | unlocks the variable, and blocks until another thread does a | |
158 | C<cond_signal> or C<cond_broadcast> for that same locked variable. | |
159 | The variable that C<cond_wait> blocked on is relocked after the | |
160 | C<cond_wait> is satisfied. If there are multiple threads | |
161 | C<cond_wait>ing on the same variable, all but one will reblock waiting | |
162 | to reacquire the lock on the variable. (So if you're only using | |
163 | C<cond_wait> for synchronisation, give up the lock as soon as | |
164 | possible). The two actions of unlocking the variable and entering the | |
165 | blocked wait state are atomic, the two actions of exiting from the | |
166 | blocked wait state and relocking the variable are not. | |
167 | ||
168 | In its second form, C<cond_wait> takes a shared, B<unlocked> variable | |
169 | followed by a shared, B<locked> variable. The second variable is | |
170 | unlocked and thread execution suspended until another thread signals | |
171 | the first variable. | |
172 | ||
173 | It is important to note that the variable can be notified even if | |
174 | no thread C<cond_signal> or C<cond_broadcast> on the variable. | |
175 | It is therefore important to check the value of the variable and | |
176 | go back to waiting if the requirement is not fulfilled. For example, | |
177 | to pause until a shared counter drops to zero: | |
178 | ||
179 | { lock($counter); cond_wait($count) until $counter == 0; } | |
180 | ||
181 | =item cond_timedwait VARIABLE, ABS_TIMEOUT | |
182 | ||
183 | =item cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR | |
184 | ||
185 | In its two-argument form, C<cond_timedwait> takes a B<locked> variable | |
186 | and an absolute timeout as parameters, unlocks the variable, and blocks | |
187 | until the timeout is reached or another thread signals the variable. A | |
188 | false value is returned if the timeout is reached, and a true value | |
189 | otherwise. In either case, the variable is re-locked upon return. | |
190 | ||
191 | Like C<cond_wait>, this function may take a shared, B<locked> variable | |
192 | as an additional parameter; in this case the first parameter is an | |
193 | B<unlocked> condition variable protected by a distinct lock variable. | |
194 | ||
195 | Again like C<cond_wait>, waking up and reacquiring the lock are not | |
196 | atomic, and you should always check your desired condition after this | |
197 | function returns. Since the timeout is an absolute value, however, it | |
198 | does not have to be recalculated with each pass: | |
199 | ||
200 | lock($var); | |
201 | my $abs = time() + 15; | |
202 | until ($ok = desired_condition($var)) { | |
203 | last if !cond_timedwait($var, $abs); | |
204 | } | |
205 | # we got it if $ok, otherwise we timed out! | |
206 | ||
207 | =item cond_signal VARIABLE | |
208 | ||
209 | The C<cond_signal> function takes a B<locked> variable as a parameter | |
210 | and unblocks one thread that's C<cond_wait>ing on that variable. If | |
211 | more than one thread is blocked in a C<cond_wait> on that variable, | |
212 | only one (and which one is indeterminate) will be unblocked. | |
213 | ||
214 | If there are no threads blocked in a C<cond_wait> on the variable, | |
215 | the signal is discarded. By always locking before signaling, you can | |
216 | (with care), avoid signaling before another thread has entered cond_wait(). | |
217 | ||
218 | C<cond_signal> will normally generate a warning if you attempt to use it | |
219 | on an unlocked variable. On the rare occasions where doing this may be | |
220 | sensible, you can skip the warning with | |
221 | ||
222 | { no warnings 'threads'; cond_signal($foo) } | |
223 | ||
224 | =item cond_broadcast VARIABLE | |
225 | ||
226 | The C<cond_broadcast> function works similarly to C<cond_signal>. | |
227 | C<cond_broadcast>, though, will unblock B<all> the threads that are | |
228 | blocked in a C<cond_wait> on the locked variable, rather than only one. | |
229 | ||
230 | =back | |
231 | ||
232 | =head1 NOTES | |
233 | ||
234 | threads::shared is designed to disable itself silently if threads are | |
235 | not available. If you want access to threads, you must C<use threads> | |
236 | before you C<use threads::shared>. threads will emit a warning if you | |
237 | use it after threads::shared. | |
238 | ||
239 | =head1 BUGS | |
240 | ||
241 | C<bless> is not supported on shared references. In the current version, | |
242 | C<bless> will only bless the thread local reference and the blessing | |
243 | will not propagate to the other threads. This is expected to be | |
244 | implemented in a future version of Perl. | |
245 | ||
246 | Does not support splice on arrays! | |
247 | ||
248 | Taking references to the elements of shared arrays and hashes does not | |
249 | autovivify the elements, and neither does slicing a shared array/hash | |
250 | over non-existent indices/keys autovivify the elements. | |
251 | ||
252 | share() allows you to C<< share $hashref->{key} >> without giving any error | |
253 | message. But the C<< $hashref->{key} >> is B<not> shared, causing the error | |
254 | "locking can only be used on shared values" to occur when you attempt to | |
255 | C<< lock $hasref->{key} >>. | |
256 | ||
257 | =head1 AUTHOR | |
258 | ||
259 | Arthur Bergman E<lt>arthur at contiller.seE<gt> | |
260 | ||
261 | threads::shared is released under the same license as Perl | |
262 | ||
263 | Documentation borrowed from the old Thread.pm | |
264 | ||
265 | =head1 SEE ALSO | |
266 | ||
267 | L<threads>, L<perlthrtut>, L<http://www.perl.com/pub/a/2002/06/11/threads.html> | |
268 | ||
269 | =cut |