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

Comparing Coro/README (file contents):
Revision 1.2 by root, Sat Aug 20 01:10:22 2005 UTC vs.
Revision 1.5 by root, Mon Dec 4 22:06:02 2006 UTC

… …
6 6
7 async { 7 async {
8 # some asynchronous thread of execution 8 # some asynchronous thread of execution
9 }; 9 };
10 10
11 # alternatively create an async process like this: 11 # alternatively create an async coroutine like this:
12 12
13 sub some_func : Coro { 13 sub some_func : Coro {
14 # some more async code 14 # some more async code
15 } 15 }
16 16
17 cede; 17 cede;
18 18
19DESCRIPTION 19DESCRIPTION
20 This module collection manages coroutines. Coroutines are similar to 20 This module collection manages coroutines. Coroutines are similar to
21 threads but don't run in parallel. 21 threads but don't run in parallel at the same time even on SMP machines.
22 The specific flavor of coroutine use din this module also guarentees you
23 that it will not switch between coroutines unless necessary, at
24 easily-identified points in your program, so locking and parallel access
25 are rarely an issue, making coroutine programming much safer than
26 threads programming.
27
28 (Perl, however, does not natively support real threads but instead does
29 a very slow and memory-intensive emulation of processes using threads.
30 This is a performance win on Windows machines, and a loss everywhere
31 else).
22 32
23 In this module, coroutines are defined as "callchain + lexical variables 33 In this module, coroutines are defined as "callchain + lexical variables
24 + @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own 34 + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
25 callchain, it's own set of lexicals and it's own set of perl's most 35 callchain, its own set of lexicals and its own set of perls most
26 important global variables. 36 important global variables.
27 37
28 $main 38 $main
29 This coroutine represents the main program. 39 This coroutine represents the main program.
30 40
31 $current (or as function: current) 41 $current (or as function: current)
32 The current coroutine (the last coroutine switched to). The initial 42 The current coroutine (the last coroutine switched to). The initial
33 value is $main (of course). 43 value is $main (of course).
34 44
45 This variable is strictly *read-only*. It is provided for
46 performance reasons. If performance is not essentiel you are
47 encouraged to use the "Coro::current" function instead.
48
35 $idle 49 $idle
36 The coroutine to switch to when no other coroutine is running. The 50 A callback that is called whenever the scheduler finds no ready
37 default implementation prints "FATAL: deadlock detected" and exits. 51 coroutines to run. The default implementation prints "FATAL:
52 deadlock detected" and exits, because the program has no other way
53 to continue.
54
55 This hook is overwritten by modules such as "Coro::Timer" and
56 "Coro::Event" to wait on an external event that hopefully wake up a
57 coroutine so the scheduler can run it.
58
59 Please note that if your callback recursively invokes perl (e.g. for
60 event handlers), then it must be prepared to be called recursively.
38 61
39 STATIC METHODS 62 STATIC METHODS
40 Static methods are actually functions that operate on the current 63 Static methods are actually functions that operate on the current
41 process only. 64 coroutine only.
42 65
43 async { ... } [@args...] 66 async { ... } [@args...]
44 Create a new asynchronous process and return it's process object 67 Create a new asynchronous coroutine and return it's coroutine object
45 (usually unused). When the sub returns the new process is 68 (usually unused). When the sub returns the new coroutine is
46 automatically terminated. 69 automatically terminated.
70
71 Calling "exit" in a coroutine will not work correctly, so do not do
72 that.
73
74 When the coroutine dies, the program will exit, just as in the main
75 program.
47 76
48 # create a new coroutine that just prints its arguments 77 # create a new coroutine that just prints its arguments
49 async { 78 async {
50 print "@_\n"; 79 print "@_\n";
51 } 1,2,3,4; 80 } 1,2,3,4;
52 81
53 schedule 82 schedule
54 Calls the scheduler. Please note that the current process will not 83 Calls the scheduler. Please note that the current coroutine will not
55 be put into the ready queue, so calling this function usually means 84 be put into the ready queue, so calling this function usually means
56 you will never be called again. 85 you will never be called again unless something else (e.g. an event
86 handler) calls ready.
87
88 The canonical way to wait on external events is this:
89
90 {
91 # remember current coroutine
92 my $current = $Coro::current;
93
94 # register a hypothetical event handler
95 on_event_invoke sub {
96 # wake up sleeping coroutine
97 $current->ready;
98 undef $current;
99 };
100
101 # call schedule until event occured.
102 # in case we are woken up for other reasons
103 # (current still defined), loop.
104 Coro::schedule while $current;
105 }
57 106
58 cede 107 cede
59 "Cede" to other processes. This function puts the current process 108 "Cede" to other coroutines. This function puts the current coroutine
60 into the ready queue and calls "schedule", which has the effect of 109 into the ready queue and calls "schedule", which has the effect of
61 giving up the current "timeslice" to other coroutines of the same or 110 giving up the current "timeslice" to other coroutines of the same or
62 higher priority. 111 higher priority.
63 112
64 terminate [arg...] 113 terminate [arg...]
65 Terminates the current process with the given status values (see 114 Terminates the current coroutine with the given status values (see
66 cancel). 115 cancel).
67 116
68 # dynamic methods 117 # dynamic methods
69 118
70 PROCESS METHODS 119 COROUTINE METHODS
71 These are the methods you can call on process objects. 120 These are the methods you can call on coroutine objects.
72 121
73 new Coro \&sub [, @args...] 122 new Coro \&sub [, @args...]
74 Create a new process and return it. When the sub returns the process 123 Create a new coroutine and return it. When the sub returns the
75 automatically terminates as if "terminate" with the returned values 124 coroutine automatically terminates as if "terminate" with the
76 were called. To make the process run you must first put it into the 125 returned values were called. To make the coroutine run you must
77 ready queue by calling the ready method. 126 first put it into the ready queue by calling the ready method.
78 127
79 $process->ready 128 Calling "exit" in a coroutine will not work correctly, so do not do
129 that.
130
131 $success = $coroutine->ready
80 Put the given process into the ready queue. 132 Put the given coroutine into the ready queue (according to it's
133 priority) and return true. If the coroutine is already in the ready
134 queue, do nothing and return false.
81 135
136 $is_ready = $coroutine->is_ready
137 Return wether the coroutine is currently the ready queue or not,
138
82 $process->cancel (arg...) 139 $coroutine->cancel (arg...)
83 Temrinates the given process and makes it return the given arguments 140 Terminates the given coroutine and makes it return the given
84 as status (default: the empty list). 141 arguments as status (default: the empty list).
85 142
86 $process->join 143 $coroutine->join
87 Wait until the coroutine terminates and return any values given to 144 Wait until the coroutine terminates and return any values given to
88 the "terminate" or "cancel" functions. "join" can be called multiple 145 the "terminate" or "cancel" functions. "join" can be called multiple
89 times from multiple processes. 146 times from multiple coroutine.
90 147
91 $oldprio = $process->prio($newprio) 148 $oldprio = $coroutine->prio ($newprio)
92 Sets (or gets, if the argument is missing) the priority of the 149 Sets (or gets, if the argument is missing) the priority of the
93 process. Higher priority processes get run before lower priority 150 coroutine. Higher priority coroutines get run before lower priority
94 processes. Priorities are small signed integers (currently -4 .. 151 coroutines. Priorities are small signed integers (currently -4 ..
95 +3), that you can refer to using PRIO_xxx constants (use the import 152 +3), that you can refer to using PRIO_xxx constants (use the import
96 tag :prio to get then): 153 tag :prio to get then):
97 154
98 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 155 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
99 3 > 1 > 0 > -1 > -3 > -4 156 3 > 1 > 0 > -1 > -3 > -4
… …
102 current->prio(PRIO_HIGH); 159 current->prio(PRIO_HIGH);
103 160
104 The idle coroutine ($Coro::idle) always has a lower priority than 161 The idle coroutine ($Coro::idle) always has a lower priority than
105 any existing coroutine. 162 any existing coroutine.
106 163
107 Changing the priority of the current process will take effect 164 Changing the priority of the current coroutine will take effect
108 immediately, but changing the priority of processes in the ready 165 immediately, but changing the priority of coroutines in the ready
109 queue (but not running) will only take effect after the next 166 queue (but not running) will only take effect after the next
110 schedule (of that process). This is a bug that will be fixed in some 167 schedule (of that coroutine). This is a bug that will be fixed in
111 future version. 168 some future version.
112 169
113 $newprio = $process->nice($change) 170 $newprio = $coroutine->nice ($change)
114 Similar to "prio", but subtract the given value from the priority 171 Similar to "prio", but subtract the given value from the priority
115 (i.e. higher values mean lower priority, just as in unix). 172 (i.e. higher values mean lower priority, just as in unix).
116 173
117 $olddesc = $process->desc($newdesc) 174 $olddesc = $coroutine->desc ($newdesc)
118 Sets (or gets in case the argument is missing) the description for 175 Sets (or gets in case the argument is missing) the description for
119 this process. This is just a free-form string you can associate with 176 this coroutine. This is just a free-form string you can associate
120 a process. 177 with a coroutine.
178
179 GLOBAL FUNCTIONS
180 Coro::nready
181 Returns the number of coroutines that are currently in the ready
182 state, i.e. that can be swicthed to. The value 0 means that the only
183 runnable coroutine is the currently running one, so "cede" would
184 have no effect, and "schedule" would cause a deadlock unless there
185 is an idle handler that wakes up some coroutines.
186
187 unblock_sub { ... }
188 This utility function takes a BLOCK or code reference and "unblocks"
189 it, returning the new coderef. This means that the new coderef will
190 return immediately without blocking, returning nothing, while the
191 original code ref will be called (with parameters) from within its
192 own coroutine.
193
194 The reason this fucntion exists is that many event libraries (such
195 as the venerable Event module) are not coroutine-safe (a weaker form
196 of thread-safety). This means you must not block within event
197 callbacks, otherwise you might suffer from crashes or worse.
198
199 This function allows your callbacks to block by executing them in
200 another coroutine where it is safe to block. One example where
201 blocking is handy is when you use the Coro::AIO functions to save
202 results to disk.
203
204 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
205 when creating event callbacks that want to block.
121 206
122BUGS/LIMITATIONS 207BUGS/LIMITATIONS
123 - you must make very sure that no coro is still active on global 208 - you must make very sure that no coro is still active on global
124 destruction. very bad things might happen otherwise (usually segfaults). 209 destruction. very bad things might happen otherwise (usually segfaults).
125 210

Diff Legend

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