This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
t/japh/abigail.t (was: FETCH for tied $" called an odd number of times.)
[perl5.git] / ext / threads / shared / shared.pm
CommitLineData
b050c948 1package threads::shared;
b050c948
AB
2use strict;
3use warnings;
4use Config;
a446a88f
NIS
5
6require Exporter;
7our @ISA = qw(Exporter);
8our @EXPORT = qw(share cond_wait cond_broadcast cond_signal unlock);
9c4972d9 9our @EXPORT_OK = qw(_id _thrcnt _refcnt);
a446a88f
NIS
10our $VERSION = '0.90';
11
b050c948 12
9c4972d9 13if ($Config{'useithreads'}) {
6f942b98
AB
14 *cond_wait = \&cond_wait_enabled;
15 *cond_signal = \&cond_signal_enabled;
16 *cond_broadcast = \&cond_broadcast_enabled;
17 *unlock = \&unlock_enabled;
9c4972d9
NIS
18 require XSLoader;
19 XSLoader::load('threads::shared',$VERSION);
20}
21else {
a6b94e59
AB
22 *share = \&share_disabled;
23 *cond_wait = \&cond_wait_disabled;
24 *cond_signal = \&cond_signal_disabled;
dab065ea 25 *cond_broadcast = \&cond_broadcast_disabled;
a6b94e59 26 *unlock = \&unlock_disabled;
b050c948
AB
27}
28
b050c948 29
b050c948
AB
30sub cond_wait_disabled { return @_ };
31sub cond_signal_disabled { return @_};
32sub cond_broadcast_disabled { return @_};
33sub unlock_disabled { 1 };
34sub lock_disabled { 1 }
35sub share_disabled { return @_}
36
dab065ea
AB
37$threads::shared::threads_shared = 1;
38
6b85e4fe
NIS
39sub _thrcnt { 42 }
40
41sub threads::shared::tie::SPLICE
42{
43 die "Splice not implemented for shared arrays";
44}
45
b050c948
AB
46
47__END__
48
49=head1 NAME
50
51threads::shared - Perl extension for sharing data structures between threads
52
53=head1 SYNOPSIS
54
55 use threads::shared;
56
57 my($foo, @foo, %foo);
aaf3876d
AB
58 share($foo);
59 share(@foo);
60 share(%hash);
b050c948
AB
61 my $bar = share([]);
62 $hash{bar} = share({});
63
515f0976
AB
64 lock(%hash);
65 unlock(%hash);
b050c948 66 cond_wait($scalar);
515f0976
AB
67 cond_broadcast(@array);
68 cond_signal(%hash);
b050c948
AB
69
70=head1 DESCRIPTION
71
ad91d581
JH
72This modules allows you to share() variables. These variables will
73then be shared across different threads (and pseudoforks on
74win32). They are used together with the threads module.
b050c948 75
515f0976 76=head1 EXPORT
b050c948 77
515f0976
AB
78C<share>, C<lock>, C<unlock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>
79
80=head1 FUNCTIONS
81
82=over 4
83
84=item share VARIABLE
85
d1be9408 86C<share> takes a value and marks it as shared, you can share a scalar, array, hash
515f0976
AB
87scalar ref, array ref and hash ref, C<share> will return the shared value.
88
89C<share> will traverse up references exactly I<one> level.
90C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.
91
92=item lock VARIABLE
93
94C<lock> places a lock on a variable until the lock goes out of scope. If
95the variable is locked by another thread, the C<lock> call will block until
96it's available. C<lock> is recursive, so multiple calls to C<lock> are
97safe--the variable will remain locked until the outermost lock on the
21312124 98variable goes out of scope or C<unlock> is called enough times to match
515f0976
AB
99the number of calls to <lock>.
100
101If a container object, such as a hash or array, is locked, all the elements
102of that container are not locked. For example, if a thread does a C<lock
103@a>, any other thread doing a C<lock($a[12])> won't block.
104
105C<lock> will traverse up references exactly I<one> level.
106C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.
107
108
109=item unlock VARIABLE
110
111C<unlock> takes a locked shared value and decrements the lock count.
112If the lock count is zero the variable is unlocked. It is not necessary
113to call C<unlock> but it can be usefull to reduce lock contention.
114
115C<unlock> will traverse up references exactly I<one> level.
116C<unlock(\$a)> is equivalent to C<unlock($a)>, while C<unlock(\\$a)> is not.
117
118=item cond_wait VARIABLE
119
120The C<cond_wait> function takes a B<locked> variable as a parameter,
121unlocks the variable, and blocks until another thread does a C<cond_signal>
122or C<cond_broadcast> for that same locked variable. The variable that
123C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.
124If there are multiple threads C<cond_wait>ing on the same variable, all but
125one will reblock waiting to reaquire the lock on the variable. (So if
126you're only using C<cond_wait> for synchronization, give up the lock as
127soon as possible)
128
129It is important to note that the variable can be notified even if no
130thread C<cond_signal> or C<cond_broadcast> on the variable. It is therefore
131important to check the value of the variable and go back to waiting if the
132requirment is not fullfilled.
133
134=item cond_signal VARIABLE
135
136The C<cond_signal> function takes a B<locked> variable as a parameter and
137unblocks one thread that's C<cond_wait>ing on that variable. If more than
138one thread is blocked in a C<cond_wait> on that variable, only one (and
139which one is indeterminate) will be unblocked.
140
141If there are no threads blocked in a C<cond_wait> on the variable, the
142signal is discarded.
143
144=item cond_broadcast VARIABLE
145
146The C<cond_broadcast> function works similarly to C<cond_signal>.
147C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
148in a C<cond_wait> on the locked variable, rather than only one.
b050c948 149
dab065ea
AB
150
151=head1 NOTES
152
8c5dce87 153threads::shared is designed to disable itself silently if threads are
dab065ea
AB
154not available. If you want access to threads, you must C<use threads>
155before you C<use threads::shared>. threads will emit a warning if you
8c5dce87 156use it after threads::shared.
dab065ea 157
b050c948
AB
158=head1 BUGS
159
515f0976
AB
160C<bless> is not supported on shared references, in the current version
161C<bless> will only bless the thread local reference and the blessing
162will not propagate to the other threads, this is expected to be implmented
163in the future.
164
b050c948 165Does not support splice on arrays!
b050c948
AB
166
167=head1 AUTHOR
168
aaf3876d 169Arthur Bergman E<lt>arthur at contiller.seE<gt>
b050c948 170
aaf3876d 171threads::shared is released under the same license as Perl
b050c948 172
515f0976
AB
173Documentation borrowed from Thread.pm
174
b050c948
AB
175=head1 SEE ALSO
176
177L<perl> L<threads>
178
179=cut
515f0976
AB
180
181
182
183
184