ext/threads/threads.pm

   1 package threads;
   2
   3 use 5.7.2;
   4 use strict;
   5 use warnings;
   6
   7 use overload
   8     '==' => \&equals,
   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 equals {
  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 5005 threads by creating a new perl
  73 interpreter per thread and not sharing any data or state between threads.
  74
  75 Prior to perl 5.8 this has only been available to people embedding perl and
  76 for emulating fork() on windows.
  77
  78 The threads API is loosly based on the old Thread.pm API. It is very important
  79 to note that variables are not shared between threads, all variables are per
  80 default thread local. To use shared variables one must use threads::shared.
  81
  82 It is also important to note that you preferebly enable threads by doing
  83 C<use threads> as early as possible and it is not possible to enable threading
  84 by in an eval "";
  85
  86 =over
  87
  88 =item new, function, LIST
  89
  90 This will create a new thread with the entry point function and give
  91 it LIST as parameters.  It will return the corresponding threads
  92 object.
  93
  94 create is an alias to new
  95
  96 =item $thread->join
  97
  98 This will wait for the corresponding thread to join. When it finishes join will return the return values of the root function.
  99 If a thread has been detached, join will return without wait.
 100
 101 =item $thread->detach
 102
 103 Will throw away the return value from the thread and make non joinable
 104
 105 =item threads->self
 106
 107 This will return the object for the current thread.
 108
 109 =item $thread->tid
 110
 111 This will return the id of the thread.
 112 threads->self->tid() is a quick way to get current thread id
 113
 114 =back
 115
 116
 117 =head1 TODO
 118
 119 =over
 120
 121 =item Fix so the return value is returned when you join
 122
 123 =item Add join_all
 124
 125 =item Fix memory leaks!
 126
 127 =back
 128
 129 =head1 AUTHOR and COPYRIGHT
 130
 131 Arthur Bergman E<lt>arthur at contiller.seE<gt>
 132
 133 threads is released under the same license as Perl
 134
 135 Thanks to
 136
 137 Richard Soderberg E<lt>rs at crystalflame.netE<gt>
 138 Helping me out tons, trying to find reasons for races and other weird bugs!
 139
 140 Simon Cozens E<lt>simon at brecon.co.ukE<gt>
 141 Being there to answer zillions of annoying questions
 142
 143 Rocco Caputo E<lt>troc at netrus.netE<gt>
 144
 145 Vipul Ved Prakash E<lt>mail at vipul.netE<gt>
 146 Helping with debugging.
 147
 148 please join perl-ithreads@perl.org for more information
 149
 150 =head1 BUGS
 151
 152 =over
 153
 154 =item creating a thread from within a thread is unsafe under win32
 155
 156 =item PERL_OLD_SIGNALS are not threadsafe, will not be.
 157
 158
 159 =back
 160
 161 =head1 SEE ALSO
 162
 163 L<perl>, L<threads::shared>, L<perlcall>, L<perlembed>, L<perlguts>
 164
 165 =cut