This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
More signedness nits.
[perl5.git] / ext / threads / threads.pm
CommitLineData
47ba8780
AB
1package threads;
2
1b553737 3use 5.007_002;
47ba8780
AB
4use strict;
5use warnings;
6
68795e93 7use overload
43d3ddbe 8 '==' => \&equal,
47ba8780
AB
9 'fallback' => 1;
10
47ba8780
AB
11#use threads::Shared;
12
dab065ea
AB
13BEGIN {
14 warn "Warning, threads::shared has already been loaded. ".
15 "To enable shared variables for these modules 'use threads' ".
16 "must be called before any of those modules are loaded\n"
17 if($threads::shared::threads_shared);
18}
19
47ba8780
AB
20require Exporter;
21require DynaLoader;
22
47ba8780
AB
23our @ISA = qw(Exporter DynaLoader);
24
25our %EXPORT_TAGS = ( all => [qw()]);
26
27our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
28
29our @EXPORT = qw(
30
31);
32our $VERSION = '0.05';
33
47ba8780 34
43d3ddbe 35sub equal {
47ba8780
AB
36 return 1 if($_[0]->tid() == $_[1]->tid());
37 return 0;
38}
39
8222d950 40$threads::threads = 1;
47ba8780
AB
41
42bootstrap threads $VERSION;
43
68795e93
NIS
44# why document 'new' then use 'create' in the tests!
45*create = \&new;
46
47ba8780
AB
47# Preloaded methods go here.
48
491;
50__END__
51
52=head1 NAME
53
54threads - Perl extension allowing use of interpreter based threads from perl
55
56=head1 SYNOPSIS
57
47ba8780
AB
58use threads;
59
60sub start_thread {
61 print "Thread started\n";
62}
63
9c4972d9 64my $thread = threads->create("start_thread","argument");
47ba8780 65
9c4972d9 66$thread->create(sub { print "I am a thread"},"argument");
47ba8780
AB
67
68$thread->join();
69
70$thread->detach();
71
72$thread = threads->self();
73
11c51ed3
AB
74threads->tid();
75threads->self->tid();
76
77$thread->tid();
47ba8780 78
47ba8780
AB
79=head1 DESCRIPTION
80
43d3ddbe
JH
81Perl 5.6 introduced something called interpreter threads. Interpreter
82threads are different from "5005threads" (the thread model of Perl
835.005) by creating a new perl interpreter per thread and not sharing
84any data or state between threads.
11c51ed3 85
43d3ddbe
JH
86Prior to perl 5.8 this has only been available to people embedding
87perl and for emulating fork() on windows.
11c51ed3 88
43d3ddbe
JH
89The threads API is loosely based on the old Thread.pm API. It is very
90important to note that variables are not shared between threads, all
91variables are per default thread local. To use shared variables one
92must use threads::shared.
11c51ed3 93
43d3ddbe
JH
94It is also important to note that you preferably enable threads by
95doing C<use threads> as early as possible and that it is not possible
dab065ea
AB
96to enable threading inside an eval ""; In particular, if you are
97intending to share variables with threads::shared, you must
98C<use threads> before you C<use threads::shared> and threads will emit
99a warning if you do it the other way around.
47ba8780
AB
100
101=over
102
9c4972d9 103=item $thread = threads->create(function, LIST)
47ba8780 104
ad91d581
JH
105This will create a new thread with the entry point function and give
106it LIST as parameters. It will return the corresponding threads
107object.
47ba8780 108
11c51ed3 109=item $thread->join
47ba8780 110
43d3ddbe
JH
111This will wait for the corresponding thread to join. When it finishes
112join will return the return values of the entry point function. If a
113thread has been detached, join will return without wait.
47ba8780 114
11c51ed3 115=item $thread->detach
47ba8780 116
43d3ddbe
JH
117Will throw away the return value from the thread and make it
118non-joinable.
47ba8780
AB
119
120=item threads->self
121
122This will return the object for the current thread.
123
11c51ed3 124=item $thread->tid
47ba8780 125
43d3ddbe
JH
126This will return the id of the thread. threads->self->tid() is a
127quick way to get current thread id.
47ba8780
AB
128
129=back
130
e4f9f4fe
JH
131=head1 WARNINGS
132
133=over 4
134
135=item Cleanup skipped %d active threads
136
137The main thread exited while there were still other threads running.
4f5d0762
JH
138This is not a good sign: you should either explicitly join the threads,
139or somehow be certain that all the non-main threads have finished.
e4f9f4fe
JH
140
141=back
47ba8780
AB
142
143=head1 TODO
144
145=over
146
43d3ddbe 147=item Fix so the return value is returned when you join.
47ba8780 148
43d3ddbe 149=item Add join_all.
47ba8780
AB
150
151=item Fix memory leaks!
152
153=back
154
155=head1 AUTHOR and COPYRIGHT
156
11c51ed3 157Arthur Bergman E<lt>arthur at contiller.seE<gt>
47ba8780 158
43d3ddbe 159threads is released under the same license as Perl.
47ba8780 160
68795e93 161Thanks to
47ba8780 162
68795e93 163Richard Soderberg E<lt>rs at crystalflame.netE<gt>
ad91d581 164Helping me out tons, trying to find reasons for races and other weird bugs!
47ba8780 165
ad91d581
JH
166Simon Cozens E<lt>simon at brecon.co.ukE<gt>
167Being there to answer zillions of annoying questions
47ba8780 168
ad91d581 169Rocco Caputo E<lt>troc at netrus.netE<gt>
47ba8780 170
ad91d581 171Vipul Ved Prakash E<lt>mail at vipul.netE<gt>
47ba8780
AB
172Helping with debugging.
173
174please join perl-ithreads@perl.org for more information
175
176=head1 BUGS
177
178=over
179
180=item creating a thread from within a thread is unsafe under win32
181
b5807cdb
AB
182=item PERL_OLD_SIGNALS are not threadsafe, will not be.
183
11c51ed3 184
47ba8780
AB
185=back
186
187=head1 SEE ALSO
188
11c51ed3 189L<perl>, L<threads::shared>, L<perlcall>, L<perlembed>, L<perlguts>
47ba8780
AB
190
191=cut