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