Skip new threads::shared test unless -Duseithreads

[p5sagit/p5-mst-13.2.git] / ext / threads / threads.pm

diff --git a/ext/threads/threads.pm b/ext/threads/threads.pm
index ef0f412..a925898 100755 (executable)
--- a/ext/threads/threads.pm
+++ b/ext/threads/threads.pm
@@ -4,17 +4,22 @@ use 5.7.2;
 use strict;
 use warnings;
 
-use overload 
-    '==' => \&equals,
+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;
 
-use Devel::Peek;
-
 our @ISA = qw(Exporter DynaLoader);
 
 our %EXPORT_TAGS = ( all => [qw()]);
@@ -26,22 +31,19 @@ our @EXPORT = qw(
 );
 our $VERSION = '0.05';
 
-sub new {
-    my $class = shift;
-    print (Dump($_[0]));
-    return $class->create(@_);
-}
-
 
-sub equals {
+sub equal {
     return 1 if($_[0]->tid() == $_[1]->tid());
     return 0;
 }
 
-$Config::threads = 1;
+$threads::threads = 1;
 
 bootstrap threads $VERSION;
 
+# why document 'new' then use 'create' in the tests!
+*create = \&new;
+
 # Preloaded methods go here.
 
 1;
@@ -59,9 +61,9 @@ sub start_thread {
     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();
 
@@ -69,41 +71,60 @@ $thread->detach();
 
 $thread = threads->self();
 
-thread->tid();
+threads->tid();
+threads->self->tid();
+
+$thread->tid();
 
 =head1 DESCRIPTION
 
-Perl 5.6 has something called interpreter threads, interpreter threads
-are built on MULTIPLICITY and allows for several different perl
-interpreters to run in different threads. This has been used in win32
-perl to fake forks, it has also been available to people embedding
-perl.
+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.
+
+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 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.
 
-=item $threads->join
+=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 $threads->detach
+=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
 
 This will return the object for the current thread.
 
-=item $threads->tid
+=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
 
@@ -112,9 +133,9 @@ threads->self->tid() is a quick way to get current thread id
 
 =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!
 
@@ -122,13 +143,13 @@ threads->self->tid() is a quick way to get current thread id
 
 =head1 AUTHOR and COPYRIGHT
 
-Artur Bergman E<lt>artur at contiller.seE<gt>
+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>
@@ -149,10 +170,11 @@ please join perl-ithreads@perl.org for more information
 
 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
 
+
 =back
 
 =head1 SEE ALSO
 
-L<perl>, L<perlcall>, L<perlembed>, L<perlguts>
+L<perl>, L<threads::shared>, L<perlcall>, L<perlembed>, L<perlguts>
 
 =cut