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

Diff Legend

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