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