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