Commit | Line | Data |
b050c948 |
1 | package threads::shared; |
73e09c8f |
2 | |
3 | use 5.007_003; |
b050c948 |
4 | use strict; |
5 | use warnings; |
6 | use Config; |
a446a88f |
7 | |
73e09c8f |
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 |
30 | require Exporter; |
31 | our @ISA = qw(Exporter); |
81f1a921 |
32 | our @EXPORT = qw(share cond_wait cond_broadcast cond_signal _refcnt _id _thrcnt); |
a446a88f |
33 | our $VERSION = '0.90'; |
34 | |
9c4972d9 |
35 | if ($Config{'useithreads'}) { |
6f942b98 |
36 | *cond_wait = \&cond_wait_enabled; |
37 | *cond_signal = \&cond_signal_enabled; |
38 | *cond_broadcast = \&cond_broadcast_enabled; |
9c4972d9 |
39 | require XSLoader; |
40 | XSLoader::load('threads::shared',$VERSION); |
41 | } |
42 | else { |
a6b94e59 |
43 | *share = \&share_disabled; |
44 | *cond_wait = \&cond_wait_disabled; |
45 | *cond_signal = \&cond_signal_disabled; |
dab065ea |
46 | *cond_broadcast = \&cond_broadcast_disabled; |
b050c948 |
47 | } |
48 | |
b050c948 |
49 | |
b050c948 |
50 | sub cond_wait_disabled { return @_ }; |
51 | sub cond_signal_disabled { return @_}; |
52 | sub cond_broadcast_disabled { return @_}; |
b050c948 |
53 | sub share_disabled { return @_} |
54 | |
dab065ea |
55 | $threads::shared::threads_shared = 1; |
56 | |
6b85e4fe |
57 | sub _thrcnt { 42 } |
58 | |
59 | sub threads::shared::tie::SPLICE |
60 | { |
61 | die "Splice not implemented for shared arrays"; |
62 | } |
63 | |
b050c948 |
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 |
73 | use threads::shared; |
74 | |
4cab98c0 |
75 | my($scalar, @array, %hash); |
76 | share($scalar); |
77 | share(@array); |
aaf3876d |
78 | share(%hash); |
b050c948 |
79 | my $bar = share([]); |
80 | $hash{bar} = share({}); |
81 | |
515f0976 |
82 | lock(%hash); |
83 | unlock(%hash); |
b050c948 |
84 | cond_wait($scalar); |
515f0976 |
85 | cond_broadcast(@array); |
86 | cond_signal(%hash); |
b050c948 |
87 | |
88 | =head1 DESCRIPTION |
89 | |
ad91d581 |
90 | This modules allows you to share() variables. These variables will |
91 | then be shared across different threads (and pseudoforks on |
92 | win32). They are used together with the threads module. |
b050c948 |
93 | |
515f0976 |
94 | =head1 EXPORT |
b050c948 |
95 | |
515f0976 |
96 | C<share>, C<lock>, C<unlock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast> |
97 | |
98 | =head1 FUNCTIONS |
99 | |
100 | =over 4 |
101 | |
102 | =item share VARIABLE |
103 | |
4cab98c0 |
104 | C<share> takes a value and marks it as shared. You can share a scalar, array, |
105 | hash, scalar ref, array ref or hash ref. C<share> will return the shared value. |
515f0976 |
106 | |
107 | C<share> will traverse up references exactly I<one> level. |
108 | C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not. |
109 | |
110 | =item lock VARIABLE |
111 | |
112 | C<lock> places a lock on a variable until the lock goes out of scope. If |
113 | the variable is locked by another thread, the C<lock> call will block until |
114 | it's available. C<lock> is recursive, so multiple calls to C<lock> are |
4cab98c0 |
115 | safe -- the variable will remain locked until the outermost lock on the |
21312124 |
116 | variable goes out of scope or C<unlock> is called enough times to match |
515f0976 |
117 | the number of calls to <lock>. |
118 | |
119 | If a container object, such as a hash or array, is locked, all the elements |
120 | of that container are not locked. For example, if a thread does a C<lock |
121 | @a>, any other thread doing a C<lock($a[12])> won't block. |
122 | |
123 | C<lock> will traverse up references exactly I<one> level. |
124 | C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not. |
125 | |
126 | |
127 | =item unlock VARIABLE |
128 | |
4cab98c0 |
129 | C<unlock> takes a B<locked> variable and decrements the lock count. |
515f0976 |
130 | If the lock count is zero the variable is unlocked. It is not necessary |
4cab98c0 |
131 | to call C<unlock> but it can be useful to reduce lock contention. |
515f0976 |
132 | |
133 | C<unlock> will traverse up references exactly I<one> level. |
134 | C<unlock(\$a)> is equivalent to C<unlock($a)>, while C<unlock(\\$a)> is not. |
135 | |
136 | =item cond_wait VARIABLE |
137 | |
138 | The C<cond_wait> function takes a B<locked> variable as a parameter, |
139 | unlocks the variable, and blocks until another thread does a C<cond_signal> |
140 | or C<cond_broadcast> for that same locked variable. The variable that |
141 | C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied. |
142 | If there are multiple threads C<cond_wait>ing on the same variable, all but |
4cab98c0 |
143 | one will reblock waiting to reacquire the lock on the variable. (So if |
515f0976 |
144 | you're only using C<cond_wait> for synchronization, give up the lock as |
145 | soon as possible) |
146 | |
147 | It is important to note that the variable can be notified even if no |
148 | thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore |
149 | important to check the value of the variable and go back to waiting if the |
4cab98c0 |
150 | requirement is not fulfilled. |
515f0976 |
151 | |
152 | =item cond_signal VARIABLE |
153 | |
154 | The C<cond_signal> function takes a B<locked> variable as a parameter and |
155 | unblocks one thread that's C<cond_wait>ing on that variable. If more than |
156 | one thread is blocked in a C<cond_wait> on that variable, only one (and |
157 | which one is indeterminate) will be unblocked. |
158 | |
159 | If there are no threads blocked in a C<cond_wait> on the variable, the |
160 | signal is discarded. |
161 | |
162 | =item cond_broadcast VARIABLE |
163 | |
164 | The C<cond_broadcast> function works similarly to C<cond_signal>. |
165 | C<cond_broadcast>, though, will unblock B<all> the threads that are blocked |
166 | in a C<cond_wait> on the locked variable, rather than only one. |
b050c948 |
167 | |
4cab98c0 |
168 | =back |
dab065ea |
169 | |
170 | =head1 NOTES |
171 | |
8c5dce87 |
172 | threads::shared is designed to disable itself silently if threads are |
dab065ea |
173 | not available. If you want access to threads, you must C<use threads> |
174 | before you C<use threads::shared>. threads will emit a warning if you |
8c5dce87 |
175 | use it after threads::shared. |
dab065ea |
176 | |
b050c948 |
177 | =head1 BUGS |
178 | |
4cab98c0 |
179 | C<bless> is not supported on shared references. In the current version, |
515f0976 |
180 | C<bless> will only bless the thread local reference and the blessing |
4cab98c0 |
181 | will not propagate to the other threads. This is expected to be |
182 | implemented in a future version of Perl. |
515f0976 |
183 | |
b050c948 |
184 | Does not support splice on arrays! |
b050c948 |
185 | |
186 | =head1 AUTHOR |
187 | |
aaf3876d |
188 | Arthur Bergman E<lt>arthur at contiller.seE<gt> |
b050c948 |
189 | |
aaf3876d |
190 | threads::shared is released under the same license as Perl |
b050c948 |
191 | |
515f0976 |
192 | Documentation borrowed from Thread.pm |
193 | |
b050c948 |
194 | =head1 SEE ALSO |
195 | |
196 | L<perl> L<threads> |
197 | |
198 | =cut |
515f0976 |
199 | |
200 | |
201 | |
202 | |
203 | |