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

Comparing Coro/README (file contents):
Revision 1.35 by root, Wed Feb 11 19:30:34 2015 UTC vs.
Revision 1.39 by root, Fri Jul 14 13:14:32 2017 UTC

417 program, as "async" does. As the coro is being reused, stuff like 417 program, as "async" does. As the coro is being reused, stuff like
418 "on_destroy" will not work in the expected way, unless you call 418 "on_destroy" will not work in the expected way, unless you call
419 terminate or cancel, which somehow defeats the purpose of pooling 419 terminate or cancel, which somehow defeats the purpose of pooling
420 (but is fine in the exceptional case). 420 (but is fine in the exceptional case).
421 421
422 The priority will be reset to 0 after each run, tracing will be 422 The priority will be reset to 0 after each run, all "swap_sv" calls
423 disabled, the description will be reset and the default output 423 will be undone, tracing will be disabled, the description will be
424 filehandle gets restored, so you can change all these. Otherwise the 424 reset and the default output filehandle gets restored, so you can
425 coro will be re-used "as-is": most notably if you change other 425 change all these. Otherwise the coro will be re-used "as-is": most
426 per-coro global stuff such as $/ you *must needs* revert that 426 notably if you change other per-coro global stuff such as $/ you
427 change, which is most simply done by using local as in: "local $/". 427 *must needs* revert that change, which is most simply done by using
428 local as in: "local $/".
428 429
429 The idle pool size is limited to 8 idle coros (this can be adjusted 430 The idle pool size is limited to 8 idle coros (this can be adjusted
430 by changing $Coro::POOL_SIZE), but there can be as many non-idle 431 by changing $Coro::POOL_SIZE), but there can be as many non-idle
431 coros as required. 432 coros as required.
432 433
533 # at this place, the timezone is Antarctica/South_Pole, 534 # at this place, the timezone is Antarctica/South_Pole,
534 # without disturbing the TZ of any other coro. 535 # without disturbing the TZ of any other coro.
535 }; 536 };
536 537
537 This can be used to localise about any resource (locale, uid, 538 This can be used to localise about any resource (locale, uid,
538 current working directory etc.) to a block, despite the existance of 539 current working directory etc.) to a block, despite the existence of
539 other coros. 540 other coros.
540 541
541 Another interesting example implements time-sliced multitasking 542 Another interesting example implements time-sliced multitasking
542 using interval timers (this could obviously be optimised, but does 543 using interval timers (this could obviously be optimised, but does
543 the job): 544 the job):
625 $state->is_new 626 $state->is_new
626 Returns true iff this Coro object is "new", i.e. has never been run 627 Returns true iff this Coro object is "new", i.e. has never been run
627 yet. Those states basically consist of only the code reference to 628 yet. Those states basically consist of only the code reference to
628 call and the arguments, but consumes very little other resources. 629 call and the arguments, but consumes very little other resources.
629 New states will automatically get assigned a perl interpreter when 630 New states will automatically get assigned a perl interpreter when
630 they are transfered to. 631 they are transferred to.
631 632
632 $state->is_zombie 633 $state->is_zombie
633 Returns true iff the Coro object has been cancelled, i.e. it's 634 Returns true iff the Coro object has been cancelled, i.e. it's
634 resources freed because they were "cancel"'ed, "terminate"'d, 635 resources freed because they were "cancel"'ed, "terminate"'d,
635 "safe_cancel"'ed or simply went out of scope. 636 "safe_cancel"'ed or simply went out of scope.
857 otherwise you might suffer from crashes or worse. The only event 858 otherwise you might suffer from crashes or worse. The only event
858 library currently known that is safe to use without "unblock_sub" is 859 library currently known that is safe to use without "unblock_sub" is
859 EV (but you might still run into deadlocks if all event loops are 860 EV (but you might still run into deadlocks if all event loops are
860 blocked). 861 blocked).
861 862
862 Coro will try to catch you when you block in the event loop 863 Coro will try to catch you when you block in the event loop ("FATAL:
863 ("FATAL:$Coro::idle blocked itself"), but this is just best effort 864 $Coro::idle blocked itself"), but this is just best effort and only
864 and only works when you do not run your own event loop. 865 works when you do not run your own event loop.
865 866
866 This function allows your callbacks to block by executing them in 867 This function allows your callbacks to block by executing them in
867 another coro where it is safe to block. One example where blocking 868 another coro where it is safe to block. One example where blocking
868 is handy is when you use the Coro::AIO functions to save results to 869 is handy is when you use the Coro::AIO functions to save results to
869 disk, for example. 870 disk, for example.
906 It is very common for a coro to wait for some callback to be called. 907 It is very common for a coro to wait for some callback to be called.
907 This occurs naturally when you use coro in an otherwise event-based 908 This occurs naturally when you use coro in an otherwise event-based
908 program, or when you use event-based libraries. 909 program, or when you use event-based libraries.
909 910
910 These typically register a callback for some event, and call that 911 These typically register a callback for some event, and call that
911 callback when the event occured. In a coro, however, you typically want 912 callback when the event occurred. In a coro, however, you typically want
912 to just wait for the event, simplyifying things. 913 to just wait for the event, simplyifying things.
913 914
914 For example "AnyEvent->child" registers a callback to be called when a 915 For example "AnyEvent->child" registers a callback to be called when a
915 specific child has exited: 916 specific child has exited:
916 917
1035 processes. What makes it so bad is that on non-windows platforms, you 1036 processes. What makes it so bad is that on non-windows platforms, you
1036 can actually take advantage of custom hardware for this purpose (as 1037 can actually take advantage of custom hardware for this purpose (as
1037 evidenced by the forks module, which gives you the (i-) threads API, 1038 evidenced by the forks module, which gives you the (i-) threads API,
1038 just much faster). 1039 just much faster).
1039 1040
1040 Sharing data is in the i-threads model is done by transfering data 1041 Sharing data is in the i-threads model is done by transferring data
1041 structures between threads using copying semantics, which is very slow - 1042 structures between threads using copying semantics, which is very slow -
1042 shared data simply does not exist. Benchmarks using i-threads which are 1043 shared data simply does not exist. Benchmarks using i-threads which are
1043 communication-intensive show extremely bad behaviour with i-threads (in 1044 communication-intensive show extremely bad behaviour with i-threads (in
1044 fact, so bad that Coro, which cannot take direct advantage of multiple 1045 fact, so bad that Coro, which cannot take direct advantage of multiple
1045 CPUs, is often orders of magnitude faster because it shares data using 1046 CPUs, is often orders of magnitude faster because it shares data using
1074 1075
1075 XS API: Coro::MakeMaker. 1076 XS API: Coro::MakeMaker.
1076 1077
1077 Low level Configuration, Thread Environment, Continuations: Coro::State. 1078 Low level Configuration, Thread Environment, Continuations: Coro::State.
1078 1079
1079AUTHOR 1080AUTHOR/SUPPORT/CONTACT
1080 Marc Lehmann <schmorp@schmorp.de> 1081 Marc A. Lehmann <schmorp@schmorp.de>
1081 http://home.schmorp.de/ 1082 http://software.schmorp.de/pkg/Coro.html
1082 1083

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines