make PPPort/harness build on VMS
[p5sagit/p5-mst-13.2.git] / ext / threads / threads.pm
1 package threads;
2
3 use 5.7.2;
4 use strict;
5 use warnings;
6
7 use overload 
8     '==' => \&equal,
9     'fallback' => 1;
10
11 #use threads::Shared;
12
13 require Exporter;
14 require DynaLoader;
15
16 our @ISA = qw(Exporter DynaLoader);
17
18 our %EXPORT_TAGS = ( all => [qw()]);
19
20 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
21
22 our @EXPORT = qw(
23         
24 );
25 our $VERSION = '0.05';
26
27
28 sub equal {
29     return 1 if($_[0]->tid() == $_[1]->tid());
30     return 0;
31 }
32
33 $threads::threads = 1;
34
35 bootstrap threads $VERSION;
36
37 # Preloaded methods go here.
38
39 1;
40 __END__
41
42 =head1 NAME
43
44 threads - Perl extension allowing use of interpreter based threads from perl
45
46 =head1 SYNOPSIS
47
48 use threads;
49
50 sub start_thread {
51     print "Thread started\n";
52 }
53
54 my $thread = threads->new("start_thread","argument");
55
56 $thread->new(sub { print "I am a thread"},"argument");
57
58 $thread->join();
59
60 $thread->detach();
61
62 $thread = threads->self();
63
64 threads->tid();
65 threads->self->tid();
66
67 $thread->tid();
68
69 =head1 DESCRIPTION
70
71 Perl 5.6 introduced something called interpreter threads.  Interpreter
72 threads are different from "5005threads" (the thread model of Perl
73 5.005) by creating a new perl interpreter per thread and not sharing
74 any data or state between threads.
75
76 Prior to perl 5.8 this has only been available to people embedding
77 perl and for emulating fork() on windows.
78
79 The threads API is loosely based on the old Thread.pm API. It is very
80 important to note that variables are not shared between threads, all
81 variables are per default thread local.  To use shared variables one
82 must use threads::shared.
83
84 It is also important to note that you preferably enable threads by
85 doing C<use threads> as early as possible and that it is not possible
86 to enable threading inside an eval "";
87
88 =over
89
90 =item $thread = new(function, LIST)
91
92 This will create a new thread with the entry point function and give
93 it LIST as parameters.  It will return the corresponding threads
94 object.
95
96 create() is an alias to new.
97
98 =item $thread->join
99
100 This will wait for the corresponding thread to join. When it finishes
101 join will return the return values of the entry point function.  If a
102 thread has been detached, join will return without wait.
103
104 =item $thread->detach
105
106 Will throw away the return value from the thread and make it
107 non-joinable.
108
109 =item threads->self
110
111 This will return the object for the current thread.
112
113 =item $thread->tid
114
115 This will return the id of the thread.  threads->self->tid() is a
116 quick way to get current thread id.
117
118 =back
119
120
121 =head1 TODO
122
123 =over
124
125 =item Fix so the return value is returned when you join.
126
127 =item Add join_all.
128
129 =item Fix memory leaks!
130
131 =back
132
133 =head1 AUTHOR and COPYRIGHT
134
135 Arthur Bergman E<lt>arthur at contiller.seE<gt>
136
137 threads is released under the same license as Perl.
138
139 Thanks to 
140
141 Richard Soderberg E<lt>rs at crystalflame.netE<gt> 
142 Helping me out tons, trying to find reasons for races and other weird bugs!
143
144 Simon Cozens E<lt>simon at brecon.co.ukE<gt>
145 Being there to answer zillions of annoying questions
146
147 Rocco Caputo E<lt>troc at netrus.netE<gt>
148
149 Vipul Ved Prakash E<lt>mail at vipul.netE<gt>
150 Helping with debugging.
151
152 please join perl-ithreads@perl.org for more information
153
154 =head1 BUGS
155
156 =over
157
158 =item creating a thread from within a thread is unsafe under win32
159
160 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
161
162
163 =back
164
165 =head1 SEE ALSO
166
167 L<perl>, L<threads::shared>, L<perlcall>, L<perlembed>, L<perlguts>
168
169 =cut