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