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

Comparing Coro/README (file contents):
Revision 1.28 by root, Sun Feb 13 04:39:15 2011 UTC vs.
Revision 1.29 by root, Sat Feb 19 06:51:22 2011 UTC

… …
38 are rarely an issue, making thread programming much safer and easier 38 are rarely an issue, making thread programming much safer and easier
39 than using other thread models. 39 than using other thread models.
40 40
41 Unlike the so-called "Perl threads" (which are not actually real threads 41 Unlike the so-called "Perl threads" (which are not actually real threads
42 but only the windows process emulation (see section of same name for 42 but only the windows process emulation (see section of same name for
43 more details) ported to unix, and as such act as processes), Coro 43 more details) ported to UNIX, and as such act as processes), Coro
44 provides a full shared address space, which makes communication between 44 provides a full shared address space, which makes communication between
45 threads very easy. And Coro's threads are fast, too: disabling the 45 threads very easy. And coro threads are fast, too: disabling the Windows
46 Windows process emulation code in your perl and using Coro can easily 46 process emulation code in your perl and using Coro can easily result in
47 result in a two to four times speed increase for your programs. A 47 a two to four times speed increase for your programs. A parallel matrix
48 parallel matrix multiplication benchmark runs over 300 times faster on a 48 multiplication benchmark (very communication-intensive) runs over 300
49 single core than perl's pseudo-threads on a quad core using all four 49 times faster on a single core than perls pseudo-threads on a quad core
50 cores. 50 using all four cores.
51 51
52 Coro achieves that by supporting multiple running interpreters that 52 Coro achieves that by supporting multiple running interpreters that
53 share data, which is especially useful to code pseudo-parallel processes 53 share data, which is especially useful to code pseudo-parallel processes
54 and for event-based programming, such as multiple HTTP-GET requests 54 and for event-based programming, such as multiple HTTP-GET requests
55 running concurrently. See Coro::AnyEvent to learn more on how to 55 running concurrently. See Coro::AnyEvent to learn more on how to
… …
61 important global variables (see Coro::State for more configuration and 61 important global variables (see Coro::State for more configuration and
62 background info). 62 background info).
63 63
64 See also the "SEE ALSO" section at the end of this document - the Coro 64 See also the "SEE ALSO" section at the end of this document - the Coro
65 module family is quite large. 65 module family is quite large.
66
67CORO THREAD LIFE CYCLE
68 During the long and exciting (or not) life of a coro thread, it goes
69 through a number of states:
70
71 1. Creation
72 The first thing in the life of a coro thread is it's creation -
73 obviously. The typical way to create a thread is to call the "async
74 BLOCK" function:
75
76 async {
77 # thread code goes here
78 };
79
80 You can also pass arguments, which are put in @_:
81
82 async {
83 print $_[1]; # prints 2
84 } 1, 2, 3;
85
86 This creates a new coro thread and puts it into the ready queue,
87 meaning it will run as soon as the CPU is free for it.
88
89 "async" will return a coro object - you can store this for future
90 reference or ignore it, the thread itself will keep a reference to
91 it's thread object - threads are alive on their own.
92
93 Another way to create a thread is to call the "new" constructor with
94 a code-reference:
95
96 new Coro sub {
97 # thread code goes here
98 }, @optional_arguments;
99
100 This is quite similar to calling "async", but the important
101 difference is that the new thread is not put into the ready queue,
102 so the thread will not run until somebody puts it there. "async" is,
103 therefore, identical to this sequence:
104
105 my $coro = new Coro sub {
106 # thread code goes here
107 };
108 $coro->ready;
109 return $coro;
110
111 2. Startup
112 When a new coro thread is created, only a copy of the code reference
113 and the arguments are stored, no extra memory for stacks and so on
114 is allocated, keeping the coro thread in a low-memory state.
115
116 Only when it actually starts executing will all the resources be
117 finally allocated.
118
119 The optional arguments specified at coro creation are available in
120 @_, similar to function calls.
121
122 3. Running / Blocking
123 A lot can happen after the coro thread has started running. Quite
124 usually, it will not run to the end in one go (because you could use
125 a function instead), but it will give up the CPU regularly because
126 it waits for external events.
127
128 As long as a coro thread runs, it's coro object is available in the
129 global variable $Coro::current.
130
131 The low-level way to give up the CPU is to call the scheduler, which
132 selects a new coro thread to run:
133
134 Coro::schedule;
135
136 Since running threads are not in the ready queue, calling the
137 scheduler without doing anything else will block the coro thread
138 forever - you need to arrange either for the coro to put woken up
139 (readied) by some other event or some other thread, or you can put
140 it into the ready queue before scheduling:
141
142 # this is exactly what Coro::cede does
143 $Coro::current->ready;
144 Coro::schedule;
145
146 All the higher-level synchronisation methods (Coro::Semaphore,
147 Coro::rouse_*...) are actually implemented via "->ready" and
148 "Coro::schedule".
149
150 While the coro thread is running it also might get assigned a
151 C-level thread, or the C-level thread might be unassigned from it,
152 as the Coro runtime wishes. A C-level thread needs to be assigned
153 when your perl thread calls into some C-level function and that
154 function in turn calls perl and perl then wants to switch
155 coroutines. This happens most often when you run an event loop and
156 block in the callback, or when perl itself calls some function such
157 as "AUTOLOAD" or methods via the "tie" mechanism.
158
159 4. Termination
160 Many threads actually terminate after some time. There are a number
161 of ways to terminate a coro thread, the simplest is returning from
162 the top-level code reference:
163
164 async {
165 # after returning from here, the coro thread is terminated
166 };
167
168 async {
169 return if 0.5 < rand; # terminate a little earlier, maybe
170 print "got a chance to print this\n";
171 # or here
172 };
173
174 Any values returned from the coroutine can be recovered using
175 "->join":
176
177 my $coro = async {
178 "hello, world\n" # return a string
179 };
180
181 my $hello_world = $coro->join;
182
183 print $hello_world;
184
185 Another way to terminate is to call "Coro::terminate", which at any
186 subroutine call nesting level:
187
188 async {
189 Coro::terminate "return value 1", "return value 2";
190 };
191
192 And yet another way is to "->cancel" the coro thread from another
193 thread:
194
195 my $coro = async {
196 exit 1;
197 };
198
199 $coro->cancel; # an also accept values for ->join to retrieve
200
201 Cancellation *can* be dangerous - it's a bit like calling "exit"
202 without actually exiting, and might leave C libraries and XS modules
203 in a weird state. Unlike other thread implementations, however, Coro
204 is exceptionally safe with regards to cancellation, as perl will
205 always be in a consistent state.
206
207 So, cancelling a thread that runs in an XS event loop might not be
208 the best idea, but any other combination that deals with perl only
209 (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for
210 example) is safe.
211
212 5. Cleanup
213 Threads will allocate various resources. Most but not all will be
214 returned when a thread terminates, during clean-up.
215
216 Cleanup is quite similar to throwing an uncaught exception: perl
217 will work it's way up through all subroutine calls and blocks. On
218 it's way, it will release all "my" variables, undo all "local"'s and
219 free any other resources truly local to the thread.
220
221 So, a common way to free resources is to keep them referenced only
222 by my variables:
223
224 async {
225 my $big_cache = new Cache ...;
226 };
227
228 If there are no other references, then the $big_cache object will be
229 freed when the thread terminates, regardless of how it does so.
230
231 What it does "NOT" do is unlock any Coro::Semaphores or similar
232 resources, but that's where the "guard" methods come in handy:
233
234 my $sem = new Coro::Semaphore;
235
236 async {
237 my $lock_guard = $sem->guard;
238 # if we reutrn, or die or get cancelled, here,
239 # then the semaphore will be "up"ed.
240 };
241
242 The "Guard::guard" function comes in handy for any custom cleanup
243 you might want to do:
244
245 async {
246 my $window = new Gtk2::Window "toplevel";
247 # The window will not be cleaned up automatically, even when $window
248 # gets freed, so use a guard to ensure it's destruction
249 # in case of an error:
250 my $window_guard = Guard::guard { $window->destroy };
251
252 # we are safe here
253 };
254
255 Last not least, "local" can often be handy, too, e.g. when
256 temporarily replacing the coro thread description:
257
258 sub myfunction {
259 local $Coro::current->{desc} = "inside myfunction(@_)";
260
261 # if we return or die here, the description will be restored
262 }
263
264 6. Viva La Zombie Muerte
265 Even after a thread has terminated and cleaned up it's resources,
266 the coro object still is there and stores the return values of the
267 thread. Only in this state will the coro object be "reference
268 counted" in the normal perl sense: the thread code keeps a reference
269 to it when it is active, but not after it has terminated.
270
271 The means the coro object gets freed automatically when the thread
272 has terminated and cleaned up and there arenot other references.
273
274 If there are, the coro object will stay around, and you can call
275 "->join" as many times as you wish to retrieve the result values:
276
277 async {
278 print "hi\n";
279 1
280 };
281
282 # run the async above, and free everything before returning
283 # from Coro::cede:
284 Coro::cede;
285
286 {
287 my $coro = async {
288 print "hi\n";
289 1
290 };
291
292 # run the async above, and clean up, but do not free the coro
293 # object:
294 Coro::cede;
295
296 # optionally retrieve the result values
297 my @results = $coro->join;
298
299 # now $coro goes out of scope, and presumably gets freed
300 };
66 301
67GLOBAL VARIABLES 302GLOBAL VARIABLES
68 $Coro::main 303 $Coro::main
69 This variable stores the Coro object that represents the main 304 This variable stores the Coro object that represents the main
70 program. While you cna "ready" it and do most other things you can 305 program. While you cna "ready" it and do most other things you can
… …
92 The default implementation dies with "FATAL: deadlock detected.", 327 The default implementation dies with "FATAL: deadlock detected.",
93 followed by a thread listing, because the program has no other way 328 followed by a thread listing, because the program has no other way
94 to continue. 329 to continue.
95 330
96 This hook is overwritten by modules such as "Coro::EV" and 331 This hook is overwritten by modules such as "Coro::EV" and
97 "Coro::AnyEvent" to wait on an external event that hopefully wake up 332 "Coro::AnyEvent" to wait on an external event that hopefully wakes
98 a coro so the scheduler can run it. 333 up a coro so the scheduler can run it.
99 334
100 See Coro::EV or Coro::AnyEvent for examples of using this technique. 335 See Coro::EV or Coro::AnyEvent for examples of using this technique.
101 336
102SIMPLE CORO CREATION 337SIMPLE CORO CREATION
103 async { ... } [@args...] 338 async { ... } [@args...]

Diff Legend

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