mingw/html/lib/threads.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>threads - Perl extension allowing use of interpreter based threads from perl</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;threads - Perl extension allowing use of interpreter based threads from perl</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#warnings">WARNINGS</a></li>
  26         <li><a href="#todo">TODO</a></li>
  27         <li><a href="#bugs">BUGS</a></li>
  28         <li><a href="#author_and_copyright">AUTHOR and COPYRIGHT</a></li>
  29         <li><a href="#see_also">SEE ALSO</a></li>
  30 </ul>
  31 <!-- INDEX END -->
  32
  33 <hr />
  34 <p>
  35 </p>
  36 <h1><a name="name">NAME</a></h1>
  37 <p>threads - Perl extension allowing use of interpreter based threads from perl</p>
  38 <p>
  39 </p>
  40 <hr />
  41 <h1><a name="synopsis">SYNOPSIS</a></h1>
  42 <pre>
  43     use threads;</pre>
  44 <pre>
  45     sub start_thread {
  46         print &quot;Thread started\n&quot;;
  47     }</pre>
  48 <pre>
  49     my $thread  = threads-&gt;create(&quot;start_thread&quot;,&quot;argument&quot;);
  50     my $thread2 = $thread-&gt;create(sub { print &quot;I am a thread&quot;},&quot;argument&quot;);
  51     my $thread3 = async { foreach (@files) { ... } };</pre>
  52 <pre>
  53     $thread-&gt;join();
  54     $thread-&gt;detach();</pre>
  55 <pre>
  56     $thread = threads-&gt;self();
  57     $thread = threads-&gt;object( $tid );</pre>
  58 <pre>
  59     $thread-&gt;tid();
  60     threads-&gt;tid();
  61     threads-&gt;self-&gt;tid();</pre>
  62 <pre>
  63     threads-&gt;yield();</pre>
  64 <pre>
  65     threads-&gt;list();</pre>
  66 <p>
  67 </p>
  68 <hr />
  69 <h1><a name="description">DESCRIPTION</a></h1>
  70 <p>Perl 5.6 introduced something called interpreter threads.  Interpreter
  71 threads are different from ``5005threads'' (the thread model of Perl
  72 5.005) by creating a new perl interpreter per thread and not sharing
  73 any data or state between threads by default.</p>
  74 <p>Prior to perl 5.8 this has only been available to people embedding
  75 perl and for emulating <code>fork()</code> on windows.</p>
  76 <p>The threads API is loosely based on the old Thread.pm API. It is very
  77 important to note that variables are not shared between threads, all
  78 variables are per default thread local.  To use shared variables one
  79 must use threads::shared.</p>
  80 <p>It is also important to note that you must enable threads by doing
  81 <code>use threads</code> as early as possible in the script itself and that it
  82 is not possible to enable threading inside an <code>eval &quot;&quot;</code>, <code>do</code>,
  83 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_require"><code>require</code></a>, or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a>.  In particular, if you are intending to share
  84 variables with threads::shared, you must <code>use threads</code> before you
  85 <code>use threads::shared</code> and <code>threads</code> will emit a warning if you do
  86 it the other way around.</p>
  87 <dl>
  88 <dt><strong><a name="item_create">$thread = threads-&gt;create(function, LIST)</a></strong>
  89
  90 <dd>
  91 <p>This will create a new thread with the entry point function and give
  92 it LIST as parameters.  It will return the corresponding threads
  93 object, or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> if thread creation failed. The <code>new()</code> method is an
  94 alias for create().</p>
  95 </dd>
  96 </li>
  97 <dt><strong><a name="item_join">$thread-&gt;join</a></strong>
  98
  99 <dd>
 100 <p>This will wait for the corresponding thread to join. When the thread
 101 finishes, <a href="#item_join"><code>join()</code></a> will return the return values of the entry point
 102 function. If the thread has been detached, an error will be thrown.</p>
 103 </dd>
 104 <dd>
 105 <p>The context (void, scalar or list) of the thread creation is also the
 106 context for join().  This means that if you intend to return an array
 107 from a thread, you must use <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_my"><code>my ($thread) = threads-</code></a>new(...)&gt;, and
 108 that if you intend to return a scalar, you must use <code>my $thread = ...</code>.</p>
 109 </dd>
 110 <dd>
 111 <p>If the program exits without all other threads having been either
 112 joined or detached, then a warning will be issued. (A program exits
 113 either because one of its threads explicitly calls exit(), or in the
 114 case of the main thread, reaches the end of the main program file.)</p>
 115 </dd>
 116 </li>
 117 <dt><strong><a name="item_detach">$thread-&gt;detach</a></strong>
 118
 119 <dd>
 120 <p>Will make the thread unjoinable, and cause any eventual return value
 121 to be discarded.</p>
 122 </dd>
 123 </li>
 124 <dt><strong><a name="item_self">threads-&gt;self</a></strong>
 125
 126 <dd>
 127 <p>This will return the thread object for the current thread.</p>
 128 </dd>
 129 </li>
 130 <dt><strong><a name="item_tid">$thread-&gt;tid</a></strong>
 131
 132 <dd>
 133 <p>This will return the id of the thread.  Thread IDs are integers, with
 134 the main thread in a program being 0.  Currently Perl assigns a unique
 135 tid to every thread ever created in your program, assigning the first
 136 thread to be created a tid of 1, and increasing the tid by 1 for each
 137 new thread that's created.</p>
 138 </dd>
 139 <dd>
 140 <p>NB the class method <a href="#item_tid"><code>threads-&gt;tid()</code></a> is a quick way to get the
 141 current thread id if you don't have your thread object handy.</p>
 142 </dd>
 143 </li>
 144 <dt><strong><a name="item_object">threads-&gt;object( tid )</a></strong>
 145
 146 <dd>
 147 <p>This will return the thread object for the thread associated with the
 148 specified tid.  Returns undef if there is no thread associated with the tid
 149 or no tid is specified or the specified tid is undef.</p>
 150 </dd>
 151 </li>
 152 <dt><strong><a name="item_yield">threads-&gt;yield();</a></strong>
 153
 154 <dd>
 155 <p>This is a suggestion to the OS to let this thread yield CPU time to other
 156 threads.  What actually happens is highly dependent upon the underlying
 157 thread implementation.</p>
 158 </dd>
 159 <dd>
 160 <p>You may do <code>use threads qw(yield)</code> then use just a bare <a href="#item_yield"><code>yield</code></a> in your
 161 code.</p>
 162 </dd>
 163 </li>
 164 <dt><strong><a name="item_list">threads-&gt;list();</a></strong>
 165
 166 <dd>
 167 <p>This will return a list of all non joined, non detached threads.</p>
 168 </dd>
 169 </li>
 170 <dt><strong><a name="item_async_block_3b">async BLOCK;</a></strong>
 171
 172 <dd>
 173 <p><code>async</code> creates a thread to execute the block immediately following
 174 it.  This block is treated as an anonymous sub, and so must have a
 175 semi-colon after the closing brace. Like <code>threads-&gt;new</code>, <code>async</code>
 176 returns a thread object.</p>
 177 </dd>
 178 </li>
 179 </dl>
 180 <p>
 181 </p>
 182 <hr />
 183 <h1><a name="warnings">WARNINGS</a></h1>
 184 <dl>
 185 <dt><strong><a name="item_a_thread_exited_while__25d_other_threads_were_stil">A thread exited while %d other threads were still running</a></strong>
 186
 187 <dd>
 188 <p>A thread (not necessarily the main thread) exited while there were
 189 still other threads running.  Usually it's a good idea to first collect
 190 the return values of the created threads by joining them, and only then
 191 exit from the main thread.</p>
 192 </dd>
 193 </li>
 194 </dl>
 195 <p>
 196 </p>
 197 <hr />
 198 <h1><a name="todo">TODO</a></h1>
 199 <p>The current implementation of threads has been an attempt to get
 200 a correct threading system working that could be built on,
 201 and optimized, in newer versions of perl.</p>
 202 <p>Currently the overhead of creating a thread is rather large,
 203 also the cost of returning values can be large. These are areas
 204 were there most likely will be work done to optimize what data
 205 that needs to be cloned.</p>
 206 <p>
 207 </p>
 208 <hr />
 209 <h1><a name="bugs">BUGS</a></h1>
 210 <dl>
 211 <dt><strong><a name="item_parent_2dchild_threads_2e">Parent-Child threads.</a></strong>
 212
 213 <dd>
 214 <p>On some platforms it might not be possible to destroy ``parent''
 215 threads while there are still existing child ``threads''.</p>
 216 </dd>
 217 <dd>
 218 <p>This will possibly be fixed in later versions of perl.</p>
 219 </dd>
 220 </li>
 221 <dt><strong><a name="item_tid_is_i32">tid is I32</a></strong>
 222
 223 <dd>
 224 <p>The thread id is a 32 bit integer, it can potentially overflow.
 225 This might be fixed in a later version of perl.</p>
 226 </dd>
 227 </li>
 228 <dt><strong><a name="item_returning_objects">Returning objects</a></strong>
 229
 230 <dd>
 231 <p>When you return an object the entire stash that the object is blessed
 232 as well.  This will lead to a large memory usage.  The ideal situation
 233 would be to detect the original stash if it existed.</p>
 234 </dd>
 235 </li>
 236 <dt><strong><a name="item_creating_threads_inside_begin_blocks">Creating threads inside BEGIN blocks</a></strong>
 237
 238 <dd>
 239 <p>Creating threads inside BEGIN blocks (or during the compilation phase
 240 in general) does not work.  (In Windows, trying to use <code>fork()</code> inside
 241 BEGIN blocks is an equally losing proposition, since it has been
 242 implemented in very much the same way as threads.)</p>
 243 </dd>
 244 </li>
 245 <dt><strong><a name="item_perl_old_signals_are_not_threadsafe_2c_will_not_be">PERL_OLD_SIGNALS are not threadsafe, will not be.</a></strong>
 246
 247 <dd>
 248 <p>If your Perl has been built with PERL_OLD_SIGNALS (one has
 249 to explicitly add that symbol to ccflags, see <code>perl -V</code>),
 250 signal handling is not threadsafe.</p>
 251 </dd>
 252 </li>
 253 </dl>
 254 <p>
 255 </p>
 256 <hr />
 257 <h1><a name="author_and_copyright">AUTHOR and COPYRIGHT</a></h1>
 258 <p>Arthur Bergman &lt;sky at nanisky.com&gt;</p>
 259 <p>threads is released under the same license as Perl.</p>
 260 <p>Thanks to</p>
 261 <p>Richard Soderberg &lt;perl at crystalflame.net&gt;
 262 Helping me out tons, trying to find reasons for races and other weird bugs!</p>
 263 <p>Simon Cozens &lt;simon at brecon.co.uk&gt;
 264 Being there to answer zillions of annoying questions</p>
 265 <p>Rocco Caputo &lt;troc at netrus.net&gt;</p>
 266 <p>Vipul Ved Prakash &lt;mail at vipul.net&gt;
 267 Helping with debugging.</p>
 268 <p>please join <a href="mailto:perl-ithreads@perl.org">perl-ithreads@perl.org</a> for more information</p>
 269 <p>
 270 </p>
 271 <hr />
 272 <h1><a name="see_also">SEE ALSO</a></h1>
 273 <p><a href="file://C|\msysgit\mingw\html/lib/threads/shared.html">the threads::shared manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlthrtut.html">the perlthrtut manpage</a>,
 274 <a href="http://www.perl.com/pub/a/2002/06/11/threads.html">http://www.perl.com/pub/a/2002/06/11/threads.html</a>,
 275 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlguts.html">the perlguts manpage</a></p>
 276 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 277 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 278 <big><strong><span class="block">&nbsp;threads - Perl extension allowing use of interpreter based threads from perl</span></strong></big>
 279 </td></tr>
 280 </table>
 281
 282 </body>
 283
 284 </html>