additions to Thread.pm docs from Tuomas J. Lukka

<lukka@fas.harvard.edu>

p4raw-id: //depot/perl@3347

1 files changed, 28 insertions, 4 deletions

diff --git a/ext/Thread/Thread.pm b/ext/Thread/Thread.pm
index c8bca0db71..1dacdc0482 100644
--- a/ext/Thread/Thread.pm
+++ b/ext/Thread/Thread.pm
@@ -18,22 +18,29 @@ Thread - multithreading
 
     my $t = new Thread \&start_sub, @start_args;
 
-    $t->join;
+    $result = $t->join;
+    $result = $t->eval;
+    $t->detach;
 
-    my $tid = Thread->self->tid; 
+    if($t->equal($another_thread)) {
+    	# ...
+    }
 
+    my $tid = Thread->self->tid; 
     my $tlist = Thread->list;
 
     lock($scalar);
+    yield();
 
     use Thread 'async';
 
-    use Thread 'eval';
-
 =head1 DESCRIPTION
 
 The C<Thread> module provides multithreading support for perl.
 
+WARNING: Threading is an experimental feature.  Both the interface
+and implementation are subject to change drastically.
+
 =head1 FUNCTIONS
 
 =over 8
@@ -122,6 +129,11 @@ The C<cond_broadcast> function works similarly to C<cond_wait>.
 C<cond_broadcast>, though, will unblock B<all> the threads that are blocked
 in a C<cond_wait> on the locked variable, rather than only one.
 
+=item yield
+
+The C<yield> function allows another thread to take control of the
+CPU. The exact results are implementation-dependent.
+
 =back
 
 =head1 METHODS
@@ -145,6 +157,18 @@ The C<eval> method wraps an C<eval> around a C<join>, and so waits for a
 thread to exit, passing along any values the thread might have returned.
 Errors, of course, get placed into C<$@>.
 
+=item detach
+
+C<detach> tells a thread that it is never going to be joined i.e.
+that all traces of its existence can be removed once it stops running.
+Errors in detached threads will not be visible anywhere - if you want
+to catch them, you should use $SIG{__DIE__} or something like that.
+
+=item equal 
+
+C<equal> tests whether two thread objects represent the same thread and
+returns true if they do.
+
 =item tid
 
 The C<tid> method returns the tid of a thread. The tid is a monotonically