ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/README
(Generate patch)

Comparing Coro/README (file contents):
Revision 1.18 by root, Thu Nov 20 09:37:21 2008 UTC vs.
Revision 1.19 by root, Mon Nov 24 07:55:28 2008 UTC

1NAME 1NAME
2 Coro - coroutine process abstraction 2 Coro - the only real threads in perl
3 3
4SYNOPSIS 4SYNOPSIS
5 use Coro; 5 use Coro;
6 6
7 async { 7 async {
… …
23 $lock->down; 23 $lock->down;
24 $locked = 1; 24 $locked = 1;
25 $lock->up; 25 $lock->up;
26 26
27DESCRIPTION 27DESCRIPTION
28 This module collection manages coroutines. Coroutines are similar to 28 For a tutorial-style introduction, please read the Coro::Intro manpage.
29 threads but don't (in general) run in parallel at the same time even on 29 This manpage mainly contains reference information.
30 SMP machines. The specific flavor of coroutine used in this module also 30
31 guarantees you that it will not switch between coroutines unless 31 This module collection manages continuations in general, most often in
32 the form of cooperative threads (also called coroutines in the
33 documentation). They are similar to kernel threads but don't (in
34 general) run in parallel at the same time even on SMP machines. The
35 specific flavor of thread offered by this module also guarantees you
36 that it will not switch between threads unless necessary, at
32 necessary, at easily-identified points in your program, so locking and 37 easily-identified points in your program, so locking and parallel access
33 parallel access are rarely an issue, making coroutine programming much 38 are rarely an issue, making thread programming much safer and easier
34 safer and easier than threads programming. 39 than using other thread models.
35 40
36 Unlike a normal perl program, however, coroutines allow you to have 41 Unlike the so-called "Perl threads" (which are not actually real threads
37 multiple running interpreters that share data, which is especially 42 but only the windows process emulation ported to unix), Coro provides a
38 useful to code pseudo-parallel processes and for event-based 43 full shared address space, which makes communication between threads
39 programming, such as multiple HTTP-GET requests running concurrently. 44 very easy. And threads are fast, too: disabling the Windows process
40 See Coro::AnyEvent to learn more. 45 emulation code in your perl and using Coro can easily result in a two to
46 four times speed increase for your programs.
41 47
42 Coroutines are also useful because Perl has no support for threads (the 48 Coro achieves that by supporting multiple running interpreters that
43 so called "threads" that perl offers are nothing more than the (bad) 49 share data, which is especially useful to code pseudo-parallel processes
44 process emulation coming from the Windows platform: On standard 50 and for event-based programming, such as multiple HTTP-GET requests
45 operating systems they serve no purpose whatsoever, except by making 51 running concurrently. See Coro::AnyEvent to learn more on how to
46 your programs slow and making them use a lot of memory. Best disable 52 integrate Coro into an event-based environment.
47 them when building perl, or aks your software vendor/distributor to do
48 it for you).
49 53
50 In this module, coroutines are defined as "callchain + lexical variables 54 In this module, a thread is defined as "callchain + lexical variables +
51 + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own 55 @_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
52 callchain, its own set of lexicals and its own set of perls most 56 its own set of lexicals and its own set of perls most important global
53 important global variables (see Coro::State for more configuration). 57 variables (see Coro::State for more configuration and background info).
54 58
59 See also the "SEE ALSO" section at the end of this document - the Coro
60 module family is quite large.
61
62GLOBAL VARIABLES
55 $Coro::main 63 $Coro::main
56 This variable stores the coroutine object that represents the main 64 This variable stores the coroutine object that represents the main
57 program. While you cna "ready" it and do most other things you can 65 program. While you cna "ready" it and do most other things you can
58 do to coroutines, it is mainly useful to compare again 66 do to coroutines, it is mainly useful to compare again
59 $Coro::current, to see whether you are running in the main program 67 $Coro::current, to see whether you are running in the main program
… …
68 value stored in it and use it as any other coroutine object, but you 76 value stored in it and use it as any other coroutine object, but you
69 must not otherwise modify the variable itself. 77 must not otherwise modify the variable itself.
70 78
71 $Coro::idle 79 $Coro::idle
72 This variable is mainly useful to integrate Coro into event loops. 80 This variable is mainly useful to integrate Coro into event loops.
73 It is usually better to rely on Coro::AnyEvent or L"Coro::EV", as 81 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
74 this is pretty low-level functionality. 82 is pretty low-level functionality.
75 83
76 This variable stores a callback that is called whenever the 84 This variable stores either a coroutine or a callback.
77 scheduler finds no ready coroutines to run. The default 85
78 implementation prints "FATAL: deadlock detected" and exits, because 86 If it is a callback, the it is called whenever the scheduler finds
87 no ready coroutines to run. The default implementation prints
88 "FATAL: deadlock detected" and exits, because the program has no
79 the program has no other way to continue. 89 other way to continue.
80 90
91 If it is a coroutine object, then this object will be readied
92 (without invoking any ready hooks, however) when the scheduler finds
93 no other ready coroutines to run.
94
81 This hook is overwritten by modules such as "Coro::Timer" and 95 This hook is overwritten by modules such as "Coro::EV" and
82 "Coro::AnyEvent" to wait on an external event that hopefully wake up 96 "Coro::AnyEvent" to wait on an external event that hopefully wake up
83 a coroutine so the scheduler can run it. 97 a coroutine so the scheduler can run it.
84 98
85 Note that the callback *must not*, under any circumstances, block 99 Note that the callback *must not*, under any circumstances, block
86 the current coroutine. Normally, this is achieved by having an "idle 100 the current coroutine. Normally, this is achieved by having an "idle
87 coroutine" that calls the event loop and then blocks again, and then 101 coroutine" that calls the event loop and then blocks again, and then
88 readying that coroutine in the idle handler. 102 readying that coroutine in the idle handler, or by simply placing
103 the idle coroutine in this variable.
89 104
90 See Coro::Event or Coro::AnyEvent for examples of using this 105 See Coro::Event or Coro::AnyEvent for examples of using this
91 technique. 106 technique.
92 107
93 Please note that if your callback recursively invokes perl (e.g. for 108 Please note that if your callback recursively invokes perl (e.g. for
94 event handlers), then it must be prepared to be called recursively 109 event handlers), then it must be prepared to be called recursively
95 itself. 110 itself.
96 111
97 SIMPLE COROUTINE CREATION 112SIMPLE COROUTINE CREATION
98 async { ... } [@args...] 113 async { ... } [@args...]
99 Create a new coroutine and return it's coroutine object (usually 114 Create a new coroutine and return it's coroutine object (usually
100 unused). The coroutine will be put into the ready queue, so it will 115 unused). The coroutine will be put into the ready queue, so it will
101 start running automatically on the next scheduler run. 116 start running automatically on the next scheduler run.
102 117
… …
153 168
154 If you are concerned about pooled coroutines growing a lot because a 169 If you are concerned about pooled coroutines growing a lot because a
155 single "async_pool" used a lot of stackspace you can e.g. 170 single "async_pool" used a lot of stackspace you can e.g.
156 "async_pool { terminate }" once per second or so to slowly replenish 171 "async_pool { terminate }" once per second or so to slowly replenish
157 the pool. In addition to that, when the stacks used by a handler 172 the pool. In addition to that, when the stacks used by a handler
158 grows larger than 16kb (adjustable via $Coro::POOL_RSS) it will also 173 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
159 be destroyed. 174 be destroyed.
160 175
161 STATIC METHODS 176STATIC METHODS
162 Static methods are actually functions that operate on the current 177 Static methods are actually functions that implicitly operate on the
163 coroutine. 178 current coroutine.
164 179
165 schedule 180 schedule
166 Calls the scheduler. The scheduler will find the next coroutine that 181 Calls the scheduler. The scheduler will find the next coroutine that
167 is to be run from the ready queue and switches to it. The next 182 is to be run from the ready queue and switches to it. The next
168 coroutine to be run is simply the one with the highest priority that 183 coroutine to be run is simply the one with the highest priority that
… …
211 Note that while this will try to free some of the main programs 226 Note that while this will try to free some of the main programs
212 resources, you cannot free all of them, so if a coroutine that is 227 resources, you cannot free all of them, so if a coroutine that is
213 not the main program calls this function, there will be some 228 not the main program calls this function, there will be some
214 one-time resource leak. 229 one-time resource leak.
215 230
216 COROUTINE METHODS 231COROUTINE OBJECT METHODS
217 These are the methods you can call on coroutine objects (or to create 232 These are the methods you can call on coroutine objects (or to create
218 them). 233 them).
219 234
220 new Coro \&sub [, @args...] 235 new Coro \&sub [, @args...]
221 Create a new coroutine and return it. When the sub returns, the 236 Create a new coroutine and return it. When the sub returns, the
… …
328 with a coroutine. 343 with a coroutine.
329 344
330 This method simply sets the "$coroutine->{desc}" member to the given 345 This method simply sets the "$coroutine->{desc}" member to the given
331 string. You can modify this member directly if you wish. 346 string. You can modify this member directly if you wish.
332 347
333 GLOBAL FUNCTIONS 348GLOBAL FUNCTIONS
334 Coro::nready 349 Coro::nready
335 Returns the number of coroutines that are currently in the ready 350 Returns the number of coroutines that are currently in the ready
336 state, i.e. that can be switched to by calling "schedule" directory 351 state, i.e. that can be switched to by calling "schedule" directory
337 or indirectly. The value 0 means that the only runnable coroutine is 352 or indirectly. The value 0 means that the only runnable coroutine is
338 the currently running one, so "cede" would have no effect, and 353 the currently running one, so "cede" would have no effect, and
… …
365 while the original code ref will be called (with parameters) from 380 while the original code ref will be called (with parameters) from
366 within another coroutine. 381 within another coroutine.
367 382
368 The reason this function exists is that many event libraries (such 383 The reason this function exists is that many event libraries (such
369 as the venerable Event module) are not coroutine-safe (a weaker form 384 as the venerable Event module) are not coroutine-safe (a weaker form
370 of thread-safety). This means you must not block within event 385 of reentrancy). This means you must not block within event
371 callbacks, otherwise you might suffer from crashes or worse. The 386 callbacks, otherwise you might suffer from crashes or worse. The
372 only event library currently known that is safe to use without 387 only event library currently known that is safe to use without
373 "unblock_sub" is EV. 388 "unblock_sub" is EV.
374 389
375 This function allows your callbacks to block by executing them in 390 This function allows your callbacks to block by executing them in
… …
391 some event callback, then you must not block either, or use 406 some event callback, then you must not block either, or use
392 "unblock_sub". 407 "unblock_sub".
393 408
394 $cb = Coro::rouse_cb 409 $cb = Coro::rouse_cb
395 Create and return a "rouse callback". That's a code reference that, 410 Create and return a "rouse callback". That's a code reference that,
396 when called, will save its arguments and notify the owner coroutine 411 when called, will remember a copy of its arguments and notify the
397 of the callback. 412 owner coroutine of the callback.
398 413
399 See the next function. 414 See the next function.
400 415
401 @args = Coro::rouse_wait [$cb] 416 @args = Coro::rouse_wait [$cb]
402 Wait for the specified rouse callback (or the last one tht was 417 Wait for the specified rouse callback (or the last one that was
403 created in this coroutine). 418 created in this coroutine).
404 419
405 As soon as the callback is invoked (or when the calback was invoked 420 As soon as the callback is invoked (or when the callback was invoked
406 before "rouse_wait"), it will return a copy of the arguments 421 before "rouse_wait"), it will return the arguments originally passed
407 originally passed to the rouse callback. 422 to the rouse callback.
408 423
409 See the section HOW TO WAIT FOR A CALLBACK for an actual usage 424 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
410 example. 425 example.
411 426
412HOW TO WAIT FOR A CALLBACK 427HOW TO WAIT FOR A CALLBACK
… …
480 broken), then coroutines will not survive a fork. There is no known 495 broken), then coroutines will not survive a fork. There is no known
481 workaround except to fix your libc and use a saner backend. 496 workaround except to fix your libc and use a saner backend.
482 497
483 perl process emulation ("threads") 498 perl process emulation ("threads")
484 This module is not perl-pseudo-thread-safe. You should only ever use 499 This module is not perl-pseudo-thread-safe. You should only ever use
485 this module from the same thread (this requirement might be removed 500 this module from the first thread (this requirement might be removed
486 in the future to allow per-thread schedulers, but Coro::State does 501 in the future to allow per-thread schedulers, but Coro::State does
487 not yet allow this). I recommend disabling thread support and using 502 not yet allow this). I recommend disabling thread support and using
488 processes, as having the windows process emulation enabled under 503 processes, as having the windows process emulation enabled under
489 unix roughly halves perl performance, even when not used. 504 unix roughly halves perl performance, even when not used.
490 505
… …
503 518
504 Debugging: Coro::Debug. 519 Debugging: Coro::Debug.
505 520
506 Support/Utility: Coro::Specific, Coro::Util. 521 Support/Utility: Coro::Specific, Coro::Util.
507 522
508 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, 523 Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
509 Coro::SemaphoreSet, Coro::RWLock. 524 Coro::SemaphoreSet, Coro::RWLock.
510 525
511 IO/Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO. 526 I/O and Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO.
512 527
513 Compatibility: Coro::LWP, Coro::BDB, Coro::Storable, Coro::Select. 528 Compatibility with other modules: Coro::LWP (but see also AnyEvent::HTTP
529 for a better-working alternative), Coro::BDB, Coro::Storable,
530 Coro::Select.
514 531
515 XS API: Coro::MakeMaker. 532 XS API: Coro::MakeMaker.
516 533
517 Low level Configuration, Coroutine Environment: Coro::State. 534 Low level Configuration, Thread Environment, Continuations: Coro::State.
518 535
519AUTHOR 536AUTHOR
520 Marc Lehmann <schmorp@schmorp.de> 537 Marc Lehmann <schmorp@schmorp.de>
521 http://home.schmorp.de/ 538 http://home.schmorp.de/
522 539

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines