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

Comparing Coro/README (file contents):
Revision 1.3 by root, Mon Nov 6 19:56:26 2006 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.
47 73
48 When the coroutine dies, the program will exit, just as in the main 74 When the coroutine dies, the program will exit, just as in the main
49 program. 75 program.
50 76
51 # create a new coroutine that just prints its arguments 77 # create a new coroutine that just prints its arguments
52 async { 78 async {
53 print "@_\n"; 79 print "@_\n";
54 } 1,2,3,4; 80 } 1,2,3,4;
55 81
56 schedule 82 schedule
57 Calls the scheduler. Please note that the current process will not 83 Calls the scheduler. Please note that the current coroutine will not
58 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
59 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 }
60 106
61 cede 107 cede
62 "Cede" to other processes. This function puts the current process 108 "Cede" to other coroutines. This function puts the current coroutine
63 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
64 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
65 higher priority. 111 higher priority.
66 112
67 terminate [arg...] 113 terminate [arg...]
68 Terminates the current process with the given status values (see 114 Terminates the current coroutine with the given status values (see
69 cancel). 115 cancel).
70 116
71 # dynamic methods 117 # dynamic methods
72 118
73 PROCESS METHODS 119 COROUTINE METHODS
74 These are the methods you can call on process objects. 120 These are the methods you can call on coroutine objects.
75 121
76 new Coro \&sub [, @args...] 122 new Coro \&sub [, @args...]
77 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
78 automatically terminates as if "terminate" with the returned values 124 coroutine automatically terminates as if "terminate" with the
79 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
80 ready queue by calling the ready method. 126 first put it into the ready queue by calling the ready method.
81 127
82 $process->ready 128 Calling "exit" in a coroutine will not work correctly, so do not do
129 that.
130
131 $success = $coroutine->ready
83 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.
84 135
136 $is_ready = $coroutine->is_ready
137 Return wether the coroutine is currently the ready queue or not,
138
85 $process->cancel (arg...) 139 $coroutine->cancel (arg...)
86 Terminates the given process and makes it return the given arguments 140 Terminates the given coroutine and makes it return the given
87 as status (default: the empty list). 141 arguments as status (default: the empty list).
88 142
89 $process->join 143 $coroutine->join
90 Wait until the coroutine terminates and return any values given to 144 Wait until the coroutine terminates and return any values given to
91 the "terminate" or "cancel" functions. "join" can be called multiple 145 the "terminate" or "cancel" functions. "join" can be called multiple
92 times from multiple processes. 146 times from multiple coroutine.
93 147
94 $oldprio = $process->prio($newprio) 148 $oldprio = $coroutine->prio ($newprio)
95 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
96 process. Higher priority processes get run before lower priority 150 coroutine. Higher priority coroutines get run before lower priority
97 processes. Priorities are small signed integers (currently -4 .. 151 coroutines. Priorities are small signed integers (currently -4 ..
98 +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
99 tag :prio to get then): 153 tag :prio to get then):
100 154
101 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
102 3 > 1 > 0 > -1 > -3 > -4 156 3 > 1 > 0 > -1 > -3 > -4
… …
105 current->prio(PRIO_HIGH); 159 current->prio(PRIO_HIGH);
106 160
107 The idle coroutine ($Coro::idle) always has a lower priority than 161 The idle coroutine ($Coro::idle) always has a lower priority than
108 any existing coroutine. 162 any existing coroutine.
109 163
110 Changing the priority of the current process will take effect 164 Changing the priority of the current coroutine will take effect
111 immediately, but changing the priority of processes in the ready 165 immediately, but changing the priority of coroutines in the ready
112 queue (but not running) will only take effect after the next 166 queue (but not running) will only take effect after the next
113 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
114 future version. 168 some future version.
115 169
116 $newprio = $process->nice($change) 170 $newprio = $coroutine->nice ($change)
117 Similar to "prio", but subtract the given value from the priority 171 Similar to "prio", but subtract the given value from the priority
118 (i.e. higher values mean lower priority, just as in unix). 172 (i.e. higher values mean lower priority, just as in unix).
119 173
120 $olddesc = $process->desc($newdesc) 174 $olddesc = $coroutine->desc ($newdesc)
121 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
122 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
123 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.
124 206
125BUGS/LIMITATIONS 207BUGS/LIMITATIONS
126 - 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
127 destruction. very bad things might happen otherwise (usually segfaults). 209 destruction. very bad things might happen otherwise (usually segfaults).
128 210

Diff Legend

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