This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[DOC PATCH] perlthrtut proofreading
[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
81f1a921
AB
35use Attribute::Handlers;
36
b050c948 37
9c4972d9 38if ($Config{'useithreads'}) {
6f942b98
AB
39 *cond_wait = \&cond_wait_enabled;
40 *cond_signal = \&cond_signal_enabled;
41 *cond_broadcast = \&cond_broadcast_enabled;
9c4972d9
NIS
42 require XSLoader;
43 XSLoader::load('threads::shared',$VERSION);
44}
45else {
a6b94e59
AB
46 *share = \&share_disabled;
47 *cond_wait = \&cond_wait_disabled;
48 *cond_signal = \&cond_signal_disabled;
dab065ea 49 *cond_broadcast = \&cond_broadcast_disabled;
b050c948
AB
50}
51
b050c948 52
b050c948
AB
53sub cond_wait_disabled { return @_ };
54sub cond_signal_disabled { return @_};
55sub cond_broadcast_disabled { return @_};
b050c948
AB
56sub share_disabled { return @_}
57
dab065ea
AB
58$threads::shared::threads_shared = 1;
59
6b85e4fe
NIS
60sub _thrcnt { 42 }
61
62sub threads::shared::tie::SPLICE
63{
64 die "Splice not implemented for shared arrays";
65}
66
81f1a921
AB
67sub UNIVERSAL::shared : ATTR {
68 my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
69 share($referent);
70}
b050c948
AB
71
72__END__
73
74=head1 NAME
75
76threads::shared - Perl extension for sharing data structures between threads
77
78=head1 SYNOPSIS
79
73e09c8f 80 use threads;
b050c948
AB
81 use threads::shared;
82
83 my($foo, @foo, %foo);
aaf3876d
AB
84 share($foo);
85 share(@foo);
86 share(%hash);
b050c948
AB
87 my $bar = share([]);
88 $hash{bar} = share({});
89
515f0976
AB
90 lock(%hash);
91 unlock(%hash);
b050c948 92 cond_wait($scalar);
515f0976
AB
93 cond_broadcast(@array);
94 cond_signal(%hash);
b050c948
AB
95
96=head1 DESCRIPTION
97
ad91d581
JH
98This modules allows you to share() variables. These variables will
99then be shared across different threads (and pseudoforks on
100win32). They are used together with the threads module.
b050c948 101
515f0976 102=head1 EXPORT
b050c948 103
515f0976
AB
104C<share>, C<lock>, C<unlock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
105
106=head1 FUNCTIONS
107
108=over 4
109
110=item share VARIABLE
111
d1be9408 112C<share> takes a value and marks it as shared, you can share a scalar, array, hash
515f0976
AB
113scalar ref, array ref and hash ref, C<share> will return the shared value.
114
115C<share> will traverse up references exactly I<one> level.
116C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
117
118=item lock VARIABLE
119
120C<lock> places a lock on a variable until the lock goes out of scope. If
121the variable is locked by another thread, the C<lock> call will block until
122it's available. C<lock> is recursive, so multiple calls to C<lock> are
123safe--the variable will remain locked until the outermost lock on the
21312124 124variable goes out of scope or C<unlock> is called enough times to match
515f0976
AB
125the number of calls to <lock>.
126
127If a container object, such as a hash or array, is locked, all the elements
128of that container are not locked. For example, if a thread does a C<lock
129@a>, any other thread doing a C<lock($a[12])> won't block.
130
131C<lock> will traverse up references exactly I<one> level.
132C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
133
134
135=item unlock VARIABLE
136
137C<unlock> takes a locked shared value and decrements the lock count.
138If the lock count is zero the variable is unlocked. It is not necessary
139to call C<unlock> but it can be usefull to reduce lock contention.
140
141C<unlock> will traverse up references exactly I<one> level.
142C<unlock(\$a)> is equivalent to C<unlock($a)>, while C<unlock(\\$a)> is not.
143
144=item cond_wait VARIABLE
145
146The C<cond_wait> function takes a B<locked> variable as a parameter,
147unlocks the variable, and blocks until another thread does a C<cond_signal>
148or C<cond_broadcast> for that same locked variable. The variable that
149C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
150If there are multiple threads C<cond_wait>ing on the same variable, all but
151one will reblock waiting to reaquire the lock on the variable. (So if
152you're only using C<cond_wait> for synchronization, give up the lock as
153soon as possible)
154
155It is important to note that the variable can be notified even if no
156thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore
157important to check the value of the variable and go back to waiting if the
158requirment is not fullfilled.
159
160=item cond_signal VARIABLE
161
162The C<cond_signal> function takes a B<locked> variable as a parameter and
163unblocks one thread that's C<cond_wait>ing on that variable. If more than
164one thread is blocked in a C<cond_wait> on that variable, only one (and
165which one is indeterminate) will be unblocked.
166
167If there are no threads blocked in a C<cond_wait> on the variable, the
168signal is discarded.
169
170=item cond_broadcast VARIABLE
171
172The C<cond_broadcast> function works similarly to C<cond_signal>.
173C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
174in a C<cond_wait> on the locked variable, rather than only one.
b050c948 175
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
515f0976
AB
186C<bless> is not supported on shared references, in the current version
187C<bless> will only bless the thread local reference and the blessing
188will not propagate to the other threads, this is expected to be implmented
189in the future.
190
b050c948 191Does not support splice on arrays!
b050c948
AB
192
193=head1 AUTHOR
194
aaf3876d 195Arthur Bergman E<lt>arthur at contiller.seE<gt>
b050c948 196
aaf3876d 197threads::shared is released under the same license as Perl
b050c948 198
515f0976
AB
199Documentation borrowed from Thread.pm
200
b050c948
AB
201=head1 SEE ALSO
202
203L<perl> L<threads>
204
205=cut
515f0976
AB
206
207
208
209
210