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

Comparing Coro/README (file contents):
Revision 1.17 by root, Wed Nov 5 15:38:10 2008 UTC vs.
Revision 1.18 by root, Thu Nov 20 09:37:21 2008 UTC

… …
60 or not. 60 or not.
61 61
62 $Coro::current 62 $Coro::current
63 The coroutine object representing the current coroutine (the last 63 The coroutine object representing the current coroutine (the last
64 coroutine that the Coro scheduler switched to). The initial value is 64 coroutine that the Coro scheduler switched to). The initial value is
65 $main (of course). 65 $Coro::main (of course).
66 66
67 This variable is strictly *read-only*. You can take copies of the 67 This variable is strictly *read-only*. You can take copies of the
68 value stored in it and use it as any other coroutine object, but you 68 value stored in it and use it as any other coroutine object, but you
69 must not otherwise modify the variable itself. 69 must not otherwise modify the variable itself.
70 70
… …
126 Similar to "async", but uses a coroutine pool, so you should not 126 Similar to "async", but uses a coroutine pool, so you should not
127 call terminate or join on it (although you are allowed to), and you 127 call terminate or join on it (although you are allowed to), and you
128 get a coroutine that might have executed other code already (which 128 get a coroutine that might have executed other code already (which
129 can be good or bad :). 129 can be good or bad :).
130 130
131 On the plus side, this function is faster than creating (and 131 On the plus side, this function is about twice as fast as creating
132 destroying) a completly new coroutine, so if you need a lot of 132 (and destroying) a completely new coroutine, so if you need a lot of
133 generic coroutines in quick successsion, use "async_pool", not 133 generic coroutines in quick successsion, use "async_pool", not
134 "async". 134 "async".
135 135
136 The code block is executed in an "eval" context and a warning will 136 The code block is executed in an "eval" context and a warning will
137 be issued in case of an exception instead of terminating the 137 be issued in case of an exception instead of terminating the
… …
180 yours to call "->ready" on that once some event happens, and last 180 yours to call "->ready" on that once some event happens, and last
181 you call "schedule" to put yourself to sleep. Note that a lot of 181 you call "schedule" to put yourself to sleep. Note that a lot of
182 things can wake your coroutine up, so you need to check whether the 182 things can wake your coroutine up, so you need to check whether the
183 event indeed happened, e.g. by storing the status in a variable. 183 event indeed happened, e.g. by storing the status in a variable.
184 184
185 The canonical way to wait on external events is this: 185 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
186 186 callbacks.
187 {
188 # remember current coroutine
189 my $current = $Coro::current;
190
191 # register a hypothetical event handler
192 on_event_invoke sub {
193 # wake up sleeping coroutine
194 $current->ready;
195 undef $current;
196 };
197
198 # call schedule until event occurred.
199 # in case we are woken up for other reasons
200 # (current still defined), loop.
201 Coro::schedule while $current;
202 }
203 187
204 cede 188 cede
205 "Cede" to other coroutines. This function puts the current coroutine 189 "Cede" to other coroutines. This function puts the current coroutine
206 into the ready queue and calls "schedule", which has the effect of 190 into the ready queue and calls "schedule", which has the effect of
207 giving up the current "timeslice" to other coroutines of the same or 191 giving up the current "timeslice" to other coroutines of the same or
… …
258 $coroutine->cancel (arg...) 242 $coroutine->cancel (arg...)
259 Terminates the given coroutine and makes it return the given 243 Terminates the given coroutine and makes it return the given
260 arguments as status (default: the empty list). Never returns if the 244 arguments as status (default: the empty list). Never returns if the
261 coroutine is the current coroutine. 245 coroutine is the current coroutine.
262 246
247 $coroutine->schedule_to
248 Puts the current coroutine to sleep (like "Coro::schedule"), but
249 instead of continuing with the next coro from the ready queue,
250 always switch to the given coroutine object (regardless of priority
251 etc.). The readyness state of that coroutine isn't changed.
252
253 This is an advanced method for special cases - I'd love to hear
254 about any uses for this one.
255
256 $coroutine->cede_to
257 Like "schedule_to", but puts the current coroutine into the ready
258 queue. This has the effect of temporarily switching to the given
259 coroutine, and continuing some time later.
260
261 This is an advanced method for special cases - I'd love to hear
262 about any uses for this one.
263
263 $coroutine->throw ([$scalar]) 264 $coroutine->throw ([$scalar])
264 If $throw is specified and defined, it will be thrown as an 265 If $throw is specified and defined, it will be thrown as an
265 exception inside the coroutine at the next convenient point in time 266 exception inside the coroutine at the next convenient point in time.
266 (usually after it gains control at the next schedule/transfer/cede).
267 Otherwise clears the exception object. 267 Otherwise clears the exception object.
268
269 Coro will check for the exception each time a schedule-like-function
270 returns, i.e. after each "schedule", "cede",
271 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
272 these functions detect this case and return early in case an
273 exception is pending.
268 274
269 The exception object will be thrown "as is" with the specified 275 The exception object will be thrown "as is" with the specified
270 scalar in $@, i.e. if it is a string, no line number or newline will 276 scalar in $@, i.e. if it is a string, no line number or newline will
271 be appended (unlike with "die"). 277 be appended (unlike with "die").
272 278
… …
383 when you use a module that uses AnyEvent (and you use 389 when you use a module that uses AnyEvent (and you use
384 Coro::AnyEvent) and it provides callbacks that are the result of 390 Coro::AnyEvent) and it provides callbacks that are the result of
385 some event callback, then you must not block either, or use 391 some event callback, then you must not block either, or use
386 "unblock_sub". 392 "unblock_sub".
387 393
394 $cb = Coro::rouse_cb
395 Create and return a "rouse callback". That's a code reference that,
396 when called, will save its arguments and notify the owner coroutine
397 of the callback.
398
399 See the next function.
400
401 @args = Coro::rouse_wait [$cb]
402 Wait for the specified rouse callback (or the last one tht was
403 created in this coroutine).
404
405 As soon as the callback is invoked (or when the calback was invoked
406 before "rouse_wait"), it will return a copy of the arguments
407 originally passed to the rouse callback.
408
409 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
410 example.
411
412HOW TO WAIT FOR A CALLBACK
413 It is very common for a coroutine to wait for some callback to be
414 called. This occurs naturally when you use coroutines in an otherwise
415 event-based program, or when you use event-based libraries.
416
417 These typically register a callback for some event, and call that
418 callback when the event occured. In a coroutine, however, you typically
419 want to just wait for the event, simplyifying things.
420
421 For example "AnyEvent->child" registers a callback to be called when a
422 specific child has exited:
423
424 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
425
426 But from withina coroutine, you often just want to write this:
427
428 my $status = wait_for_child $pid;
429
430 Coro offers two functions specifically designed to make this easy,
431 "Coro::rouse_cb" and "Coro::rouse_wait".
432
433 The first function, "rouse_cb", generates and returns a callback that,
434 when invoked, will save it's arguments and notify the coroutine that
435 created the callback.
436
437 The second function, "rouse_wait", waits for the callback to be called
438 (by calling "schedule" to go to sleep) and returns the arguments
439 originally passed to the callback.
440
441 Using these functions, it becomes easy to write the "wait_for_child"
442 function mentioned above:
443
444 sub wait_for_child($) {
445 my ($pid) = @_;
446
447 my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
448
449 my ($rpid, $rstatus) = Coro::rouse_wait;
450 $rstatus
451 }
452
453 In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
454 you can roll your own, using "schedule":
455
456 sub wait_for_child($) {
457 my ($pid) = @_;
458
459 # store the current coroutine in $current,
460 # and provide result variables for the closure passed to ->child
461 my $current = $Coro::current;
462 my ($done, $rstatus);
463
464 # pass a closure to ->child
465 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
466 $rstatus = $_[1]; # remember rstatus
467 $done = 1; # mark $rstatus as valud
468 });
469
470 # wait until the closure has been called
471 schedule while !$done;
472
473 $rstatus
474 }
475
388BUGS/LIMITATIONS 476BUGS/LIMITATIONS
477 fork with pthread backend
478 When Coro is compiled using the pthread backend (which isn't
479 recommended but required on many BSDs as their libcs are completely
480 broken), then coroutines will not survive a fork. There is no known
481 workaround except to fix your libc and use a saner backend.
482
483 perl process emulation ("threads")
389 This module is not perl-pseudo-thread-safe. You should only ever use 484 This module is not perl-pseudo-thread-safe. You should only ever use
390 this module from the same thread (this requirement might be removed in 485 this module from the same thread (this requirement might be removed
391 the future to allow per-thread schedulers, but Coro::State does not yet 486 in the future to allow per-thread schedulers, but Coro::State does
392 allow this). I recommend disabling thread support and using processes, 487 not yet allow this). I recommend disabling thread support and using
393 as this is much faster and uses less memory. 488 processes, as having the windows process emulation enabled under
489 unix roughly halves perl performance, even when not used.
490
491 coroutine switching not signal safe
492 You must not switch to another coroutine from within a signal
493 handler (only relevant with %SIG - most event libraries provide safe
494 signals).
495
496 That means you *MUST NOT* call any function that might "block" the
497 current coroutine - "cede", "schedule" "Coro::Semaphore->down" or
498 anything that calls those. Everything else, including calling
499 "ready", works.
394 500
395SEE ALSO 501SEE ALSO
396 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 502 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
397 503
398 Debugging: Coro::Debug. 504 Debugging: Coro::Debug.

Diff Legend

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