This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Storable status tweak.
[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
17Having threads support requires all of Perl and all of the modules in
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
57sub _thrcnt { 42 }
58
59sub threads::shared::tie::SPLICE
60{
61 die "Splice not implemented for shared arrays";
62}
63
b050c948
AB
64__END__
65
66=head1 NAME
67
68threads::shared - Perl extension for sharing data structures between threads
69
70=head1 SYNOPSIS
71
73e09c8f 72 use threads;
b050c948
AB
73 use threads::shared;
74
4cab98c0
SG
75 my($scalar, @array, %hash);
76 share($scalar);
77 share(@array);
aaf3876d 78 share(%hash);
b050c948
AB
79 my $bar = share([]);
80 $hash{bar} = share({});
81
515f0976
AB
82 lock(%hash);
83 unlock(%hash);
b050c948 84 cond_wait($scalar);
515f0976
AB
85 cond_broadcast(@array);
86 cond_signal(%hash);
b050c948
AB
87
88=head1 DESCRIPTION
89
ad91d581
JH
90This modules allows you to share() variables. These variables will
91then be shared across different threads (and pseudoforks on
92win32). They are used together with the threads module.
b050c948 93
515f0976 94=head1 EXPORT
b050c948 95
515f0976
AB
96C<share>, C<lock>, C<unlock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
97
98=head1 FUNCTIONS
99
100=over 4
101
102=item share VARIABLE
103
4cab98c0
SG
104C<share> takes a value and marks it as shared. You can share a scalar, array,
105hash, scalar ref, array ref or hash ref. C<share> will return the shared value.
515f0976
AB
106
107C<share> will traverse up references exactly I<one> level.
108C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
109
110=item lock VARIABLE
111
112C<lock> places a lock on a variable until the lock goes out of scope. If
113the variable is locked by another thread, the C<lock> call will block until
114it's available. C<lock> is recursive, so multiple calls to C<lock> are
4cab98c0 115safe -- the variable will remain locked until the outermost lock on the
21312124 116variable goes out of scope or C<unlock> is called enough times to match
515f0976
AB
117the number of calls to <lock>.
118
119If a container object, such as a hash or array, is locked, all the elements
120of that container are not locked. For example, if a thread does a C<lock
121@a>, any other thread doing a C<lock($a[12])> won't block.
122
123C<lock> will traverse up references exactly I<one> level.
124C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
125
126
127=item unlock VARIABLE
128
4cab98c0 129C<unlock> takes a B<locked> variable and decrements the lock count.
515f0976 130If the lock count is zero the variable is unlocked. It is not necessary
4cab98c0 131to call C<unlock> but it can be useful to reduce lock contention.
515f0976
AB
132
133C<unlock> will traverse up references exactly I<one> level.
134C<unlock(\$a)> is equivalent to C<unlock($a)>, while C<unlock(\\$a)> is not.
135
136=item cond_wait VARIABLE
137
138The C<cond_wait> function takes a B<locked> variable as a parameter,
139unlocks the variable, and blocks until another thread does a C<cond_signal>
140or C<cond_broadcast> for that same locked variable. The variable that
141C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
142If there are multiple threads C<cond_wait>ing on the same variable, all but
4cab98c0 143one will reblock waiting to reacquire the lock on the variable. (So if
515f0976
AB
144you're only using C<cond_wait> for synchronization, give up the lock as
145soon as possible)
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
160signal is discarded.
161
162=item cond_broadcast VARIABLE
163
164The C<cond_broadcast> function works similarly to C<cond_signal>.
165C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
166in a C<cond_wait> on the locked variable, rather than only one.
b050c948 167
4cab98c0 168=back
dab065ea
AB
169
170=head1 NOTES
171
8c5dce87 172threads::shared is designed to disable itself silently if threads are
dab065ea
AB
173not available. If you want access to threads, you must C<use threads>
174before you C<use threads::shared>. threads will emit a warning if you
8c5dce87 175use it after threads::shared.
dab065ea 176
b050c948
AB
177=head1 BUGS
178
4cab98c0 179C<bless> is not supported on shared references. In the current version,
515f0976 180C<bless> will only bless the thread local reference and the blessing
4cab98c0
SG
181will not propagate to the other threads. This is expected to be
182implemented in a future version of Perl.
515f0976 183
b050c948 184Does not support splice on arrays!
b050c948
AB
185
186=head1 AUTHOR
187
aaf3876d 188Arthur Bergman E<lt>arthur at contiller.seE<gt>
b050c948 189
aaf3876d 190threads::shared is released under the same license as Perl
b050c948 191
515f0976
AB
192Documentation borrowed from Thread.pm
193
b050c948
AB
194=head1 SEE ALSO
195
196L<perl> L<threads>
197
198=cut
515f0976
AB
199
200
201
202
203