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