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

Comparing Coro/README (file contents):
Revision 1.15 by root, Sun Sep 21 01:23:26 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 completely 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
… …
142 142
143 The priority will be reset to 0 after each run, tracing will be 143 The priority will be reset to 0 after each run, tracing will be
144 disabled, the description will be reset and the default output 144 disabled, the description will be reset and the default output
145 filehandle gets restored, so you can change all these. Otherwise the 145 filehandle gets restored, so you can change all these. Otherwise the
146 coroutine will be re-used "as-is": most notably if you change other 146 coroutine will be re-used "as-is": most notably if you change other
147 per-coroutine global stuff such as $/ you *must needs* to revert 147 per-coroutine global stuff such as $/ you *must needs* revert that
148 that change, which is most simply done by using local as in: " local 148 change, which is most simply done by using local as in: "local $/".
149 $/ ".
150 149
151 The pool size is limited to 8 idle coroutines (this can be adjusted 150 The idle pool size is limited to 8 idle coroutines (this can be
152 by changing $Coro::POOL_SIZE), and there can be as many non-idle 151 adjusted by changing $Coro::POOL_SIZE), but there can be as many
153 coros as required. 152 non-idle coros as required.
154 153
155 If you are concerned about pooled coroutines growing a lot because a 154 If you are concerned about pooled coroutines growing a lot because a
156 single "async_pool" used a lot of stackspace you can e.g. 155 single "async_pool" used a lot of stackspace you can e.g.
157 "async_pool { terminate }" once per second or so to slowly replenish 156 "async_pool { terminate }" once per second or so to slowly replenish
158 the pool. In addition to that, when the stacks used by a handler 157 the pool. In addition to that, when the stacks used by a handler
… …
181 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
182 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
183 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
184 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.
185 184
186 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
187 186 callbacks.
188 {
189 # remember current coroutine
190 my $current = $Coro::current;
191
192 # register a hypothetical event handler
193 on_event_invoke sub {
194 # wake up sleeping coroutine
195 $current->ready;
196 undef $current;
197 };
198
199 # call schedule until event occurred.
200 # in case we are woken up for other reasons
201 # (current still defined), loop.
202 Coro::schedule while $current;
203 }
204 187
205 cede 188 cede
206 "Cede" to other coroutines. This function puts the current coroutine 189 "Cede" to other coroutines. This function puts the current coroutine
207 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
208 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
… …
259 $coroutine->cancel (arg...) 242 $coroutine->cancel (arg...)
260 Terminates the given coroutine and makes it return the given 243 Terminates the given coroutine and makes it return the given
261 arguments as status (default: the empty list). Never returns if the 244 arguments as status (default: the empty list). Never returns if the
262 coroutine is the current coroutine. 245 coroutine is the current coroutine.
263 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
264 $coroutine->throw ([$scalar])
265 If $throw is specified and defined, it will be thrown as an
266 exception inside the coroutine at the next convenient point in time.
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.
274
275 The exception object will be thrown "as is" with the specified
276 scalar in $@, i.e. if it is a string, no line number or newline will
277 be appended (unlike with "die").
278
279 This can be used as a softer means than "cancel" to ask a coroutine
280 to end itself, although there is no guarantee that the exception
281 will lead to termination, and if the exception isn't caught it might
282 well end the whole program.
283
284 You might also think of "throw" as being the moral equivalent of
285 "kill"ing a coroutine with a signal (in this case, a scalar).
286
264 $coroutine->join 287 $coroutine->join
265 Wait until the coroutine terminates and return any values given to 288 Wait until the coroutine terminates and return any values given to
266 the "terminate" or "cancel" functions. "join" can be called 289 the "terminate" or "cancel" functions. "join" can be called
267 concurrently from multiple coroutines, and all will be resumed and 290 concurrently from multiple coroutines, and all will be resumed and
268 given the status return once the $coroutine terminates. 291 given the status return once the $coroutine terminates.
… …
304 this coroutine. This is just a free-form string you can associate 327 this coroutine. This is just a free-form string you can associate
305 with a coroutine. 328 with a coroutine.
306 329
307 This method simply sets the "$coroutine->{desc}" member to the given 330 This method simply sets the "$coroutine->{desc}" member to the given
308 string. You can modify this member directly if you wish. 331 string. You can modify this member directly if you wish.
309
310 $coroutine->throw ([$scalar])
311 If $throw is specified and defined, it will be thrown as an
312 exception inside the coroutine at the next convinient point in time
313 (usually after it gains control at the next schedule/transfer/cede).
314 Otherwise clears the exception object.
315
316 The exception object will be thrown "as is" with the specified
317 scalar in $@, i.e. if it is a string, no line number or newline will
318 be appended (unlike with "die").
319
320 This can be used as a softer means than "cancel" to ask a coroutine
321 to end itself, although there is no guarentee that the exception
322 will lead to termination, and if the exception isn't caught it might
323 well end the whole program.
324 332
325 GLOBAL FUNCTIONS 333 GLOBAL FUNCTIONS
326 Coro::nready 334 Coro::nready
327 Returns the number of coroutines that are currently in the ready 335 Returns the number of coroutines that are currently in the ready
328 state, i.e. that can be switched to by calling "schedule" directory 336 state, i.e. that can be switched to by calling "schedule" directory
… …
381 when you use a module that uses AnyEvent (and you use 389 when you use a module that uses AnyEvent (and you use
382 Coro::AnyEvent) and it provides callbacks that are the result of 390 Coro::AnyEvent) and it provides callbacks that are the result of
383 some event callback, then you must not block either, or use 391 some event callback, then you must not block either, or use
384 "unblock_sub". 392 "unblock_sub".
385 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
386BUGS/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")
387 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
388 this module from the same thread (this requirement might be removed in 485 this module from the same thread (this requirement might be removed
389 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
390 allow this). I recommend disabling thread support and using processes, 487 not yet allow this). I recommend disabling thread support and using
391 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.
392 500
393SEE ALSO 501SEE ALSO
394 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 502 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
395 503
396 Debugging: Coro::Debug. 504 Debugging: Coro::Debug.

Diff Legend

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