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

Diff Legend

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