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