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