package threads;
-use 5.7.2;
+use 5.007_003;
use strict;
use warnings;
+use Config;
-use overload
- '==' => \&equals,
+BEGIN {
+ unless ($Config{useithreads}) {
+ my @caller = caller(2);
+ die <<EOF;
+$caller[1] line $caller[2]:
+
+This Perl hasn't been configured and built properly for the threads
+module to work. (The 'useithreads' configuration option hasn't been used.)
+
+Having threads support requires all of Perl and all of the modules in
+the Perl installation to be rebuilt, it is not just a question of adding
+the threads module. (In other words, threaded and non-threaded Perls
+are binary incompatible.)
+
+If you want to the use the threads module, please contact the people
+who built your Perl.
+
+Cannot continue, aborting.
+EOF
+ }
+}
+
+use overload
+ '==' => \&equal,
'fallback' => 1;
#use threads::Shared;
+BEGIN {
+ warn "Warning, threads::shared has already been loaded. ".
+ "To enable shared variables for these modules 'use threads' ".
+ "must be called before any of those modules are loaded\n"
+ if($threads::shared::threads_shared);
+}
+
require Exporter;
require DynaLoader;
our $VERSION = '0.05';
-sub equals {
+sub equal {
return 1 if($_[0]->tid() == $_[1]->tid());
return 0;
}
bootstrap threads $VERSION;
+# why document 'new' then use 'create' in the tests!
+*create = \&new;
+
# Preloaded methods go here.
1;
print "Thread started\n";
}
-my $thread = threads->new("start_thread","argument");
+my $thread = threads->create("start_thread","argument");
-$thread->new(sub { print "I am a thread"},"argument");
+$thread->create(sub { print "I am a thread"},"argument");
$thread->join();
=head1 DESCRIPTION
-Perl 5.6 introduced something called interpreter threads. Interpreter
-threads are different from 5005 threads by creating a new perl
-interpreter per thread and not sharing any data or state between threads.
+Perl 5.6 introduced something called interpreter threads. Interpreter
+threads are different from "5005threads" (the thread model of Perl
+5.005) by creating a new perl interpreter per thread and not sharing
+any data or state between threads.
-Prior to perl 5.8 this has only been available to people embedding perl and
-for emulating fork() on windows.
+Prior to perl 5.8 this has only been available to people embedding
+perl and for emulating fork() on windows.
-The threads API is loosly based on the old Thread.pm API. It is very important
-to note that variables are not shared between threads, all variables are per
-default thread local. To use shared variables one must use threads::shared.
+The threads API is loosely based on the old Thread.pm API. It is very
+important to note that variables are not shared between threads, all
+variables are per default thread local. To use shared variables one
+must use threads::shared.
-It is also important to note that you preferebly enable threads by doing
-C<use threads> as early as possible and it is not possible to enable threading
-by in an eval "";
+It is also important to note that you preferably enable threads by
+doing C<use threads> as early as possible and that it is not possible
+to enable threading inside an eval ""; In particular, if you are
+intending to share variables with threads::shared, you must
+C<use threads> before you C<use threads::shared> and threads will emit
+a warning if you do it the other way around.
=over
-=item new, function, LIST
+=item $thread = threads->create(function, LIST)
This will create a new thread with the entry point function and give
it LIST as parameters. It will return the corresponding threads
object.
-create is an alias to new
-
=item $thread->join
-This will wait for the corresponding thread to join. When it finishes join will return the return values of the root function.
-If a thread has been detached, join will return without wait.
+This will wait for the corresponding thread to join. When it finishes
+join will return the return values of the entry point function. If a
+thread has been detached, join will return without wait.
=item $thread->detach
-Will throw away the return value from the thread and make non joinable
+Will throw away the return value from the thread and make it
+non-joinable.
=item threads->self
=item $thread->tid
-This will return the id of the thread.
-threads->self->tid() is a quick way to get current thread id
+This will return the id of the thread. threads->self->tid() is a
+quick way to get current thread id.
=back
+=head1 WARNINGS
+
+=over 4
+
+=item Cleanup skipped %d active threads
+
+The main thread exited while there were still other threads running.
+This is not a good sign: you should either explicitly join the threads,
+or somehow be certain that all the non-main threads have finished.
+
+=back
=head1 TODO
=over
-=item Fix so the return value is returned when you join
+=item Fix so the return value is returned when you join.
-=item Add join_all
+=item Add join_all.
=item Fix memory leaks!
Arthur Bergman E<lt>arthur at contiller.seE<gt>
-threads is released under the same license as Perl
+threads is released under the same license as Perl.
-Thanks to
+Thanks to
-Richard Soderberg E<lt>rs at crystalflame.netE<gt>
+Richard Soderberg E<lt>rs at crystalflame.netE<gt>
Helping me out tons, trying to find reasons for races and other weird bugs!
Simon Cozens E<lt>simon at brecon.co.ukE<gt>