Commit | Line | Data |
---|---|---|
b050c948 | 1 | package threads::shared; |
73e09c8f JH |
2 | |
3 | use 5.007_003; | |
b050c948 AB |
4 | use strict; |
5 | use warnings; | |
6 | use Config; | |
a446a88f | 7 | |
73e09c8f JH |
8 | BEGIN { |
9 | unless ($Config{useithreads}) { | |
10 | my @caller = caller(2); | |
11 | die <<EOF; | |
12 | $caller[1] line $caller[2]: | |
13 | ||
14 | This Perl hasn't been configured and built properly for the threads | |
15 | module to work. (The 'useithreads' configuration option hasn't been used.) | |
16 | ||
17 | Having threads support requires all of Perl and all of the modules in | |
18 | the Perl installation to be rebuilt, it is not just a question of adding | |
19 | the threads module. (In other words, threaded and non-threaded Perls | |
20 | are binary incompatible.) | |
21 | ||
22 | If you want to the use the threads module, please contact the people | |
23 | who built your Perl. | |
24 | ||
25 | Cannot continue, aborting. | |
26 | EOF | |
27 | } | |
28 | } | |
29 | ||
a446a88f NIS |
30 | require Exporter; |
31 | our @ISA = qw(Exporter); | |
81f1a921 | 32 | our @EXPORT = qw(share cond_wait cond_broadcast cond_signal _refcnt _id _thrcnt); |
a446a88f NIS |
33 | our $VERSION = '0.90'; |
34 | ||
9c4972d9 | 35 | if ($Config{'useithreads'}) { |
6f942b98 AB |
36 | *cond_wait = \&cond_wait_enabled; |
37 | *cond_signal = \&cond_signal_enabled; | |
38 | *cond_broadcast = \&cond_broadcast_enabled; | |
9c4972d9 NIS |
39 | require XSLoader; |
40 | XSLoader::load('threads::shared',$VERSION); | |
41 | } | |
42 | else { | |
a6b94e59 AB |
43 | *share = \&share_disabled; |
44 | *cond_wait = \&cond_wait_disabled; | |
45 | *cond_signal = \&cond_signal_disabled; | |
dab065ea | 46 | *cond_broadcast = \&cond_broadcast_disabled; |
b050c948 AB |
47 | } |
48 | ||
b050c948 | 49 | |
b050c948 AB |
50 | sub cond_wait_disabled { return @_ }; |
51 | sub cond_signal_disabled { return @_}; | |
52 | sub cond_broadcast_disabled { return @_}; | |
b050c948 AB |
53 | sub share_disabled { return @_} |
54 | ||
dab065ea AB |
55 | $threads::shared::threads_shared = 1; |
56 | ||
6b85e4fe NIS |
57 | sub _thrcnt { 42 } |
58 | ||
59 | sub threads::shared::tie::SPLICE | |
60 | { | |
61 | die "Splice not implemented for shared arrays"; | |
62 | } | |
63 | ||
b050c948 AB |
64 | __END__ |
65 | ||
66 | =head1 NAME | |
67 | ||
68 | threads::shared - Perl extension for sharing data structures between threads | |
69 | ||
70 | =head1 SYNOPSIS | |
71 | ||
73e09c8f | 72 | use threads; |
b050c948 AB |
73 | use threads::shared; |
74 | ||
0358cc2c CN |
75 | my $var : shared; |
76 | ||
bee2c548 CN |
77 | my($scalar, @array, %hash); |
78 | share($scalar); | |
79 | share(@array); | |
aaf3876d | 80 | share(%hash); |
b050c948 AB |
81 | my $bar = share([]); |
82 | $hash{bar} = share({}); | |
83 | ||
0358cc2c CN |
84 | { lock(%hash); ... } |
85 | ||
b050c948 | 86 | cond_wait($scalar); |
515f0976 AB |
87 | cond_broadcast(@array); |
88 | cond_signal(%hash); | |
b050c948 AB |
89 | |
90 | =head1 DESCRIPTION | |
91 | ||
0358cc2c CN |
92 | By default, variables are private to each thread, and each newly created |
93 | thread gets a private copy of each existing variable. This module allows | |
94 | you to share variables across different threads (and pseudoforks on | |
95 | win32). It is used together with the threads module. | |
b050c948 | 96 | |
515f0976 | 97 | =head1 EXPORT |
b050c948 | 98 | |
0358cc2c | 99 | C<share>, C<lock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast> |
515f0976 AB |
100 | |
101 | =head1 FUNCTIONS | |
102 | ||
103 | =over 4 | |
104 | ||
105 | =item share VARIABLE | |
106 | ||
bee2c548 CN |
107 | C<share> takes a value and marks it as shared. You can share a scalar, array, |
108 | hash, scalar ref, array ref or hash ref. C<share> will return the shared value. | |
515f0976 AB |
109 | |
110 | C<share> will traverse up references exactly I<one> level. | |
111 | C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not. | |
112 | ||
0358cc2c CN |
113 | A variable can also be marked as shared at compile time by using the |
114 | C<shared> attribute: C<my $var : shared>. | |
115 | ||
515f0976 AB |
116 | =item lock VARIABLE |
117 | ||
118 | C<lock> places a lock on a variable until the lock goes out of scope. If | |
119 | the variable is locked by another thread, the C<lock> call will block until | |
120 | it's available. C<lock> is recursive, so multiple calls to C<lock> are | |
bee2c548 | 121 | safe -- the variable will remain locked until the outermost lock on the |
0358cc2c | 122 | variable goes out of scope. |
515f0976 AB |
123 | |
124 | If a container object, such as a hash or array, is locked, all the elements | |
125 | of that container are not locked. For example, if a thread does a C<lock | |
126 | @a>, any other thread doing a C<lock($a[12])> won't block. | |
127 | ||
128 | C<lock> will traverse up references exactly I<one> level. | |
129 | C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not. | |
130 | ||
0358cc2c CN |
131 | Note that you cannot explicitly unlock a variable; you can only wait for |
132 | the lock to go out of scope. If you need more fine-grained control, see | |
133 | L<threads::shared::semaphore>. | |
515f0976 AB |
134 | |
135 | =item cond_wait VARIABLE | |
136 | ||
137 | The C<cond_wait> function takes a B<locked> variable as a parameter, | |
138 | unlocks the variable, and blocks until another thread does a C<cond_signal> | |
139 | or C<cond_broadcast> for that same locked variable. The variable that | |
140 | C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied. | |
141 | If there are multiple threads C<cond_wait>ing on the same variable, all but | |
bee2c548 | 142 | one will reblock waiting to reacquire the lock on the variable. (So if |
0358cc2c CN |
143 | you're only using C<cond_wait> for synchronisation, give up the lock as |
144 | soon as possible). The two actions of unlocking the variable and entering | |
145 | the blocked wait state are atomic, The two actions of exiting from the | |
146 | blocked wait state and relocking the variable are not. | |
515f0976 AB |
147 | |
148 | It is important to note that the variable can be notified even if no | |
149 | thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore | |
150 | important to check the value of the variable and go back to waiting if the | |
bee2c548 | 151 | requirement is not fulfilled. |
515f0976 AB |
152 | |
153 | =item cond_signal VARIABLE | |
154 | ||
155 | The C<cond_signal> function takes a B<locked> variable as a parameter and | |
156 | unblocks one thread that's C<cond_wait>ing on that variable. If more than | |
157 | one thread is blocked in a C<cond_wait> on that variable, only one (and | |
158 | which one is indeterminate) will be unblocked. | |
159 | ||
160 | If there are no threads blocked in a C<cond_wait> on the variable, the | |
0358cc2c CN |
161 | signal is discarded. By always locking before signaling, you can (with |
162 | care), avoid signaling before another thread has entered cond_wait(). | |
163 | ||
164 | C<cond_signal> will normally generate a warning if you attempt to use it | |
165 | on an unlocked variable. On the rare occasions where doing this may be | |
166 | sensible, you can skip the warning with | |
167 | ||
168 | { no warnings 'threads'; cond_signal($foo) } | |
515f0976 AB |
169 | |
170 | =item cond_broadcast VARIABLE | |
171 | ||
172 | The C<cond_broadcast> function works similarly to C<cond_signal>. | |
173 | C<cond_broadcast>, though, will unblock B<all> the threads that are blocked | |
174 | in a C<cond_wait> on the locked variable, rather than only one. | |
b050c948 | 175 | |
bee2c548 | 176 | =back |
dab065ea AB |
177 | |
178 | =head1 NOTES | |
179 | ||
8c5dce87 | 180 | threads::shared is designed to disable itself silently if threads are |
dab065ea AB |
181 | not available. If you want access to threads, you must C<use threads> |
182 | before you C<use threads::shared>. threads will emit a warning if you | |
8c5dce87 | 183 | use it after threads::shared. |
dab065ea | 184 | |
b050c948 AB |
185 | =head1 BUGS |
186 | ||
bee2c548 | 187 | C<bless> is not supported on shared references. In the current version, |
515f0976 | 188 | C<bless> will only bless the thread local reference and the blessing |
bee2c548 CN |
189 | will not propagate to the other threads. This is expected to be |
190 | implemented in a future version of Perl. | |
515f0976 | 191 | |
b050c948 | 192 | Does not support splice on arrays! |
b050c948 AB |
193 | |
194 | =head1 AUTHOR | |
195 | ||
aaf3876d | 196 | Arthur Bergman E<lt>arthur at contiller.seE<gt> |
b050c948 | 197 | |
aaf3876d | 198 | threads::shared is released under the same license as Perl |
b050c948 | 199 | |
515f0976 AB |
200 | Documentation borrowed from Thread.pm |
201 | ||
b050c948 AB |
202 | =head1 SEE ALSO |
203 | ||
204 | L<perl> L<threads> | |
205 | ||
206 | =cut | |
515f0976 AB |
207 | |
208 | ||
209 | ||
210 | ||
211 |