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