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