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