1 |
=head1 Introduction to Coro |
2 |
|
3 |
This tutorial will introduce you to the main features of the Coro module |
4 |
family. |
5 |
|
6 |
It first introduces some basic concepts, and later gives a short overview |
7 |
of the module family. |
8 |
|
9 |
|
10 |
=head1 What is Coro? |
11 |
|
12 |
Coro started as a simple module that implemented a specific form of |
13 |
first class continuations called Coroutines. These basically allow you |
14 |
to capture the current point execution and jump to another point, while |
15 |
allowing you to return at any time, as kind of non-local jump, not unlike |
16 |
C's C<setjmp>/C<longjmp>. This is nowadays known as a L<Coro::State>. |
17 |
|
18 |
The natural application for these is to include a scheduler, resulting in |
19 |
cooperative threads, which is the main use case for Coro today. Still, |
20 |
much of the documentation and custom refers to these threads as |
21 |
"coroutines" or often just "coros". |
22 |
|
23 |
A thread is very much like a stripped-down perl interpreter, or a |
24 |
process: Unlike a full interpreter process, a thread doesn't have its own |
25 |
variable or code namespaces - everything is shared. That means that when |
26 |
one thread modifies a variable (or any value, e.g. through a reference), |
27 |
then other threads immediately see this change when they look at the same |
28 |
variable or location. |
29 |
|
30 |
Cooperative means that these threads must cooperate with each other, when |
31 |
it coems to CPU usage - only one thread ever has the CPU, and if another |
32 |
thread wants the CPU, the running thread has to give it up. The latter |
33 |
is either explicitly, by calling a function to do so, or implicity, when |
34 |
waiting on a resource (such as a Semaphore, or the completion of some I/O |
35 |
request). |
36 |
|
37 |
Perl itself uses rather confusing terminilogy - what perl calls a "thread" |
38 |
is actually called a "process" everywhere else: The so-called "perl |
39 |
threads" are actually artifacts of the unix process emulation code used |
40 |
on Windows, which is consequently why they are actually processes and not |
41 |
threads. The biggest difference is that neither variables (nor code) are |
42 |
shared between processes. |
43 |
|
44 |
|
45 |
=head1 Cooperative Threads |
46 |
|
47 |
Cooperative threads is what the Coro module gives you: |
48 |
|
49 |
use Coro; |
50 |
|
51 |
To create a thread, you can use the C<async> function that automatically |
52 |
gets exported from that module: |
53 |
|
54 |
async { |
55 |
print "hello\n"; |
56 |
}; |
57 |
|
58 |
Async expects a code block as first argument (in indirect object |
59 |
notation). You can pass it more arguments, and these will end up in C<@_> |
60 |
when executing the codeblock, but since it is a closure, you can also just |
61 |
refer to any lexical variables that are currently visible. |
62 |
|
63 |
If you save the above lines in a file and execute it as a perl program, |
64 |
you will not get any output. |
65 |
|
66 |
The reasons is that, although you created a thread, and the thread is |
67 |
ready to execute (because C<async> puts it into the so-called I<ready |
68 |
queue>), it never gets any CPU time to actually execute, as the main |
69 |
program - which also is a thread almost like any other - never gives up |
70 |
the CPU but instead exits the whole program, by running off the end of the |
71 |
file. |
72 |
|
73 |
To explicitly give up the CPU, use the C<cede> function (which is often |
74 |
called C<yield> in other thread implementations): |
75 |
|
76 |
use Coro; |
77 |
|
78 |
async { |
79 |
print "hello\n"; |
80 |
}; |
81 |
|
82 |
cede; |
83 |
|
84 |
Running the above prints C<hello> and exits. |
85 |
|
86 |
This is not very interetsing, so let's try a slightly more interesting |
87 |
program: |
88 |
|
89 |
use Coro; |
90 |
|
91 |
async { |
92 |
print "async 1\n"; |
93 |
cede; |
94 |
print "async 2\n"; |
95 |
}; |
96 |
|
97 |
print "main 1\n"; |
98 |
cede; |
99 |
print "main 2\n"; |
100 |
cede; |
101 |
|
102 |
Running this program prints: |
103 |
|
104 |
main 1 |
105 |
async 1 |
106 |
main 2 |
107 |
async 2 |
108 |
|
109 |
This nicely illustrates the non-local jump ability: the main program |
110 |
prints the first line, and then yields the CPU to whatever other |
111 |
threads there are. And there is one other, which runs and prints |
112 |
"async 1", and itself yields the CPU. Since the only other thread |
113 |
available is the main program, it continues running and so on. |
114 |
|
115 |
In more detail, C<async> creates a new thread. All new threads |
116 |
start in a suspended state. To make them run, they need to be put into |
117 |
the ready queue, which is the second thing that C<async> does. Each time |
118 |
a thread gives up the CPU, Coro runs a so-called I<scheduler>. The |
119 |
scheduler selects the next thread from the ready queue, removes it from |
120 |
the queue, and runs it. |
121 |
|
122 |
C<cede> also does two things: first it puts the running thread into the |
123 |
ready queue, and then it jumps into the scheduler. This has the effect of |
124 |
giving up the CPU, but also ensures that, eventually, the thread gets |
125 |
run again. |
126 |
|
127 |
In fact, C<cede> could be implemented like this: |
128 |
|
129 |
sub my_cede { |
130 |
$Coro::current->ready; |
131 |
schedule; |
132 |
} |
133 |
|
134 |
This works because C<$Coro::current> always contains the currently running |
135 |
thread, and the scheduler itself can be called via C<Coro::schedule>. |
136 |
|
137 |
What's the effect of just calling C<schedule>? Simple, the scheduler |
138 |
selects the next ready thread and runs it - the current thread, as |
139 |
it hasn't been put into the ready queue, will go to sleep until something |
140 |
wakes it up. |
141 |
|
142 |
The following example remembers the current thread in a variable, |
143 |
creates a thread and then puts the main program to sleep. |
144 |
|
145 |
The newly created thread uses rand to wake up the main thread by |
146 |
calling its C<ready> method - or not. |
147 |
|
148 |
use Coro; |
149 |
|
150 |
my $wakeme = $Coro::current; |
151 |
|
152 |
async { |
153 |
$wakeme->ready if 0.5 < rand; |
154 |
}; |
155 |
|
156 |
schedule; |
157 |
|
158 |
Now, when you run it, one of two things happen: Either the C<async> |
159 |
thread wakes up main again, in which case the program silently exits, |
160 |
or it doesn't, in which case you get: |
161 |
|
162 |
FATAL: deadlock detected at - line 0 |
163 |
|
164 |
Why is that? When the C<async> thread falls of the end, it will be |
165 |
terminated (via a call to C<Coro::terminate>) and the scheduler gets run |
166 |
again. Since the C<async> thread hasn't woken up the main thread, |
167 |
and there aren't any other threads, there is nothing to wake up, |
168 |
and the program cannot continue. Since there I<are> threads that |
169 |
I<could> be running (main) but none are I<ready> to do so, Coro signals a |
170 |
I<deadlock> - no progress is possible. |
171 |
|
172 |
In fact, there is an important case where progress I<is>, in fact, |
173 |
possible - namely in an event-based program. In such a case, the program |
174 |
could well wait for I<external> events, such as a timeout, or some data to |
175 |
arrive on a socket. |
176 |
|
177 |
Since a deadlock in such a case would not be very useful, there is a |
178 |
module named L<Coro::AnyEvent> that integrates threads into an event |
179 |
loop. It configures Coro in a way that instead of dieing with an error |
180 |
message, it instead runs the event loop in the hope of receiving an event |
181 |
that will wake up some thread. |
182 |
|
183 |
|
184 |
=head2 Semaphores and other locks |
185 |
|
186 |
Using only C<ready>, C<cede> and C<schedule> to synchronise threads is |
187 |
difficult, especially if many threads are ready at the same time. Coro |
188 |
supports a number of primitives to help synchronising threads in easier |
189 |
ways. The first such primitives is L<Coro::Semaphore>, which implements |
190 |
counting semaphores (binary semaphores are available as L<Coro::Signal>, |
191 |
and there are L<Coro::SemaphoreSet> and L<Coro::RWLock> primitives as |
192 |
well): |
193 |
|
194 |
use Coro; |
195 |
|
196 |
my $sem = new Coro::Semaphore 0; # a locked semaphore |
197 |
|
198 |
async { |
199 |
print "unlocking semaphore\n"; |
200 |
$sem->up; |
201 |
}; |
202 |
|
203 |
print "trying to lock semaphore\n"; |
204 |
$sem->down; |
205 |
print "we got it!\n"; |
206 |
|
207 |
This program creates a I<locked> semaphore (a semaphore with count C<0>) |
208 |
and tries to lock it. Since the semaphore is already locked, this will |
209 |
block the main thread until the semaphore becomes available. |
210 |
|
211 |
This yields the CPU to the C<async> thread, which unlocks the semaphore |
212 |
(and instantly terminates itself by returning). |
213 |
|
214 |
Since the semaphore is now available, the main program locks it and |
215 |
continues. |
216 |
|
217 |
Semaphores are most often used to lock resources, or to exclude other |
218 |
threads from accessing or using a resource. For example, consider |
219 |
a very costly function (that temporarily allocates a lot of ram, for |
220 |
example). You wouldn't want to have many threads calling this function, |
221 |
so you use a semaphore: |
222 |
|
223 |
my $lock = new Coro::Semaphore; # unlocked initially |
224 |
|
225 |
sub costly_function { |
226 |
$lock->down; # acquire semaphore |
227 |
|
228 |
# do costly operation that blocks |
229 |
|
230 |
$lock->up; # unlock it |
231 |
} |
232 |
|
233 |
No matter how many threads call C<costly_function>, only one will run |
234 |
the body of it, all others will wait in the C<down> call. |
235 |
|
236 |
Why does the comment mention "operation the blocks"? That's because coro's |
237 |
threads are cooperative: unless C<costly_function> willingly gives up the |
238 |
CPU, other threads of control will simply not run. This makes locking |
239 |
superfluous in cases where the fucntion itself never gives up the CPU, but |
240 |
when dealing with the outside world, this is rare. |
241 |
|
242 |
Now consider what happens when the code C<die>s after executing C<down>, |
243 |
but before C<up>. This will leave the semaphore in a locked state, which |
244 |
usually isn't what you want: normally you would want to free the lock |
245 |
again. |
246 |
|
247 |
This is what the C<guard> method is for: |
248 |
|
249 |
my $lock = new Coro::Semaphore; # unlocked initially |
250 |
|
251 |
sub costly_function { |
252 |
my $guard = $lock->guard; # acquire guard |
253 |
|
254 |
# do costly operation that blocks |
255 |
} |
256 |
|
257 |
This method C<down>s the semaphore and returns a so-called guard |
258 |
object. Nothing happens as long as there are references to it, but when |
259 |
all references are gone, for example, when C<costly_function> returns or |
260 |
throws an exception, it will automatically call C<up> on the semaphore, |
261 |
no way to forget it. Even when the thread gets C<cancel>ed by another |
262 |
thread will the guard object ensure that the lock is freed. |
263 |
|
264 |
Apart from L<Coro::Semaphore> and L<Coro::Signal>, there is |
265 |
also a reader-writer lock (L<Coro::RWLock>) and a semaphore set |
266 |
(L<Coro::SemaphoreSet>). |
267 |
|
268 |
|
269 |
=head2 Channels |
270 |
|
271 |
Semaphores are fine, but usually you want to communicate by exchanging |
272 |
data as well. This is where L<Coro::Channel> comes in useful: Channels |
273 |
are the Coro equivalent of a unix pipe (and very similar to amiga message |
274 |
ports :) - you can put stuff into it on one side, and read data from it on |
275 |
the other. |
276 |
|
277 |
Here is a simple example that creates a thread and sends it |
278 |
numbers. The thread calculates the square of the number, and puts it |
279 |
into another channel, which the main thread reads the result from: |
280 |
|
281 |
use Coro; |
282 |
|
283 |
my $calculate = new Coro::Channel; |
284 |
my $result = new Coro::Channel; |
285 |
|
286 |
async { |
287 |
# endless loop |
288 |
while () { |
289 |
my $num = $calculate->get; # read a number |
290 |
$num **= 2; # square it |
291 |
$result->put ($num); # put the result into the result queue |
292 |
} |
293 |
}; |
294 |
|
295 |
for (1, 2, 5, 10, 77) { |
296 |
$calculate->put ($_); |
297 |
print "$_ ** 2 = ", $result->get, "\n"; |
298 |
} |
299 |
|
300 |
Gives: |
301 |
|
302 |
1 ** 2 = 1 |
303 |
2 ** 2 = 4 |
304 |
5 ** 2 = 25 |
305 |
10 ** 2 = 100 |
306 |
77 ** 2 = 5929 |
307 |
|
308 |
Both C<get> and C<put> methods can block the current thread: C<get> |
309 |
first checks whether there I<is> some data available, and if not, it block |
310 |
the current thread until some data arrives. C<put> can also block, as |
311 |
each Channel has a "maximum buffering capacity", i.e. you cannot store |
312 |
more than a specific number of items, which can be configured when the |
313 |
Channel gets created. |
314 |
|
315 |
In the above example, C<put> never blocks, as the default capacity |
316 |
of a Channel is very high. So the for loop first puts data into the |
317 |
channel, then tries to C<get> the result. Since the async thread hasn't |
318 |
put anything in there yet (on the firts iteration it hasn't even run |
319 |
yet), the result Channel is still empty, so the main thread blocks. |
320 |
|
321 |
Since the only other runnable/ready thread at this point is the squaring |
322 |
thread, it will be woken up, will C<get> the number, square it and put it |
323 |
into the result channel, waking up the main thread again. It will still |
324 |
continue to run, as waking up other threads just puts them into the ready |
325 |
queue, nothing less, nothing more. |
326 |
|
327 |
Only when the async thread tries to C<get> the next number from the |
328 |
calculate channel will it block (because nothing is there yet) and the |
329 |
main thread will continue running. And so on. |
330 |
|
331 |
In general, Coro will I<only ever block> a thread when it has to: Neither |
332 |
the Coro module itself nor any of its submodules will ever give up the |
333 |
CPU unless they have to, because they wait for some event to happen. |
334 |
|
335 |
Be careful, however: when multiple threads put numbers into C<$calculate> |
336 |
and read from C<$result>, they won't know which result is theirs. The |
337 |
solution for this is to either use a semaphore, or send not just the |
338 |
number, but also your own private result channel. |
339 |
|
340 |
L<Coro::Channel> can buffer some amount of items. |
341 |
|
342 |
|
343 |
=head2 What is mine, what is ours? |
344 |
|
345 |
What, exactly, constitutes a thread? Obviously it contains the current |
346 |
point of execution. Not so obviously, it also has to include all |
347 |
lexical variables, that means, every thread has its own set of lexical |
348 |
variables. To see why this is necessary, consider this program: |
349 |
|
350 |
use Coro; |
351 |
|
352 |
sub printit { |
353 |
my ($string) = @_; |
354 |
|
355 |
cede; |
356 |
|
357 |
print $string; |
358 |
} |
359 |
|
360 |
async { printit "Hello, " }; |
361 |
async { printit "World!\n" }; |
362 |
|
363 |
cede; cede; # do it |
364 |
|
365 |
The above prints C<Hello, World!\n>. If C<printit> wouldn't have |
366 |
its own per-thread C<$string> variable, it would probably print |
367 |
C<World!\nWorld\n>, which is rather unexpected, and would make it very |
368 |
difficult to make good use of threads. |
369 |
|
370 |
There are quite a number of other things that are per-thread: |
371 |
|
372 |
=over 4 |
373 |
|
374 |
=item $_, @_, $@ and the regex result vars, $&, %+, $1, $2, ... |
375 |
|
376 |
C<$_> is used much like a local variable, so it gets localised |
377 |
per-thread. The same is true for regex results (C<$1>, C<$2> and so on). |
378 |
|
379 |
C<@_> contains the arguments, so like lexicals, it also must be |
380 |
per-thread. |
381 |
|
382 |
C<$@> is not obviously required to be per-thread, but it is quite useful. |
383 |
|
384 |
=item $/ and the default output file handle |
385 |
|
386 |
Threads most often block when doing I/O. Since C<$/> is used when reading |
387 |
lines, it would be very inconvenient if it were a shared variable, so it is per-thread. |
388 |
|
389 |
The default output handle (see C<select>) is a difficult case: sometimes |
390 |
being global is preferable, sometimes per-thread is preferable. Since |
391 |
per-thread seems to be more common, it is per-thread. |
392 |
|
393 |
=item $SIG{__DIE__} and $SIG{__WARN__} |
394 |
|
395 |
If these weren't per-thread, then common constructs such as: |
396 |
|
397 |
eval { |
398 |
local $SIG{__DIE__} = sub { ... }; |
399 |
... |
400 |
}; |
401 |
|
402 |
Would not allow coroutine switching. Since exception-handling is |
403 |
per-thread, those variables should be per-thread too. |
404 |
|
405 |
=item Lots of other esoteric stuff |
406 |
|
407 |
For example, C<$^H> is per-thread. Most of the additional per-thread state |
408 |
is not directly visible to perl, but required to make the interpreter |
409 |
work. You won't normally notice these. |
410 |
|
411 |
=back |
412 |
|
413 |
Everything else is shared between all threads. For example, the globals |
414 |
C<$a> and C<$b> are shared. When does that matter? When using C<sort>, |
415 |
these variables become special, and therefore, switching threads when |
416 |
sorting might have surprising results. |
417 |
|
418 |
Other examples are the C<$!>, errno, C<$.>, the current input line number, |
419 |
C<$,>, C<$\>, C<$"> and many other special variables. |
420 |
|
421 |
While in some cases a good argument could be made for localising them to |
422 |
the thread, they are rarely used, and sometimes hard to localise. |
423 |
|
424 |
Future versions of Coro might include more per-thread state when it |
425 |
becomes a problem. |
426 |
|
427 |
|
428 |
=head2 Debugging |
429 |
|
430 |
Sometimes it can be useful to find out what each thread is doing (or |
431 |
which threads exist in the first place). The L<Coro::Debug> module has |
432 |
(among other goodies), a function that allows you to print a "ps"-like |
433 |
listing: |
434 |
|
435 |
use Coro::Debug; |
436 |
|
437 |
Coro::Debug::command "ps"; |
438 |
|
439 |
Running it just after C<< $calculate->get >> outputs something similar to this: |
440 |
|
441 |
PID SC RSS USES Description Where |
442 |
8917312 -C 22k 0 [main::] [introscript:20] |
443 |
8964448 N- 152 0 [coro manager] - |
444 |
8964520 N- 152 0 [unblock_sub scheduler] - |
445 |
8591752 UC 152 1 [introscript:12] |
446 |
11546944 N- 152 0 [EV idle process] - |
447 |
|
448 |
Interesting - there is more going on in the background than one would |
449 |
expect. Ignoring the extra threads, the main thread has pid |
450 |
C<8917312>, and the one started by C<async> has pid C<8591752>. |
451 |
|
452 |
The latter is also the only thread that doesn't have a description, |
453 |
simply because we haven't set one. Setting one is easy, just put it into |
454 |
C<< $Coro::current->{desc} >>: |
455 |
|
456 |
async { |
457 |
$Coro::current->{desc} = "cruncher"; |
458 |
... |
459 |
}; |
460 |
|
461 |
This can be rather useful when debugging a program, or when using the |
462 |
interactive debug shell of L<Coro::Debug>. |
463 |
|
464 |
|
465 |
=head1 The Real World - Event Loops |
466 |
|
467 |
Coro really wants to run in a program using some event loop. In fact, most |
468 |
real-world programs using Coro's threads are written in a combination of |
469 |
event-based and thread-based techniques, as it is easy to get the best of |
470 |
both worlds with Coro. |
471 |
|
472 |
Coro integrates well into any event loop supported by L<AnyEvent>, simply |
473 |
by C<use>ing L<Coro::AnyEvent>, but can take special advantage of the |
474 |
L<EV> and L<Event> modules. |
475 |
|
476 |
Here is a simple finger client, using whatever event loop L<AnyEvent> |
477 |
comes up with (L<Coro::Socket> automatically initialises all the event |
478 |
stuff): |
479 |
|
480 |
use Coro; |
481 |
use Coro::Socket; |
482 |
|
483 |
sub finger { |
484 |
my ($user, $host) = @_; |
485 |
|
486 |
my $fh = new Coro::Socket PeerHost => $host, PeerPort => "finger" |
487 |
or die "$user\@$host: $!"; |
488 |
|
489 |
print $fh "$user\n"; |
490 |
|
491 |
print "$user\@$host: $_" while <$fh>; |
492 |
print "$user\@$host: done\n"; |
493 |
} |
494 |
|
495 |
# now finger a few accounts |
496 |
for ( |
497 |
(async { finger "abc", "cornell.edu" }), |
498 |
(async { finger "sebbo", "world.std.com" }), |
499 |
(async { finger "trouble", "noc.dfn.de" }), |
500 |
) { |
501 |
$_->join; # wait for the result |
502 |
} |
503 |
|
504 |
There are quite a few new things here. First of all, there |
505 |
is L<Coro::Socket>. This module works much the same way as |
506 |
L<IO::Socket::INET>, except that it is coroutine-aware. This means that |
507 |
L<IO::Socket::INET>, when waiting for the network, will block the whole |
508 |
process - that means all threads, which is clearly undesirable. |
509 |
|
510 |
On the other hand, L<Coro::Socket> knows how to give up the CPU to other |
511 |
threads when it waits for the network, which makes parallel processing |
512 |
possible. |
513 |
|
514 |
The other new thing is the C<join> method: All we want to do in this |
515 |
example is start three C<async> threads and only exit when they have |
516 |
done their job. This could be done using a counting semaphore, but it is |
517 |
much simpler to synchronously wait for them to C<terminate>, which is |
518 |
exactly what the C<join> method does. |
519 |
|
520 |
It doesn't matter that the three async's will probably finish in a |
521 |
different order then the for loop C<join>s them - when the thread |
522 |
is still running, C<join> simply waits. If the thread has already |
523 |
terminated, it will simply fetch its return status. |
524 |
|
525 |
If you are experienced in event-based programming, you will see that the |
526 |
above program doesn't quite follow the normal pattern, where you start |
527 |
some work, and then run the event loop (e.v. C<EV::loop>). |
528 |
|
529 |
In fact, nontrivial programs follow this pattern even with Coro, so a Coro |
530 |
program that uses EV usually looks like this: |
531 |
|
532 |
use EV; |
533 |
use Coro; |
534 |
|
535 |
# start coroutines or event watchers |
536 |
|
537 |
EV::loop; # and loop |
538 |
|
539 |
In fact, for debugging, you often do something like this: |
540 |
|
541 |
use EV; |
542 |
use Coro::Debug; |
543 |
|
544 |
my $shell = new_unix_server Coro::Debug "/tmp/myshell"; |
545 |
|
546 |
EV::loop; # and loop |
547 |
|
548 |
This runs your program, but also an interactive shell on the unix domain |
549 |
socket in F</tmp/myshell>. You can use the F<socat> program to access it: |
550 |
|
551 |
# socat readline /tmp/myshell |
552 |
coro debug session. use help for more info |
553 |
|
554 |
> ps |
555 |
PID SC RSS USES Description Where |
556 |
136672312 RC 19k 177k [main::] [myprog:28] |
557 |
136710424 -- 1268 48 [coro manager] [Coro.pm:349] |
558 |
> help |
559 |
ps [w|v] show the list of all coroutines (wide, verbose) |
560 |
bt <pid> show a full backtrace of coroutine <pid> |
561 |
eval <pid> <perl> evaluate <perl> expression in context of <pid> |
562 |
trace <pid> enable tracing for this coroutine |
563 |
untrace <pid> disable tracing for this coroutine |
564 |
kill <pid> <reason> throws the given <reason> string in <pid> |
565 |
cancel <pid> cancels this coroutine |
566 |
ready <pid> force <pid> into the ready queue |
567 |
<anything else> evaluate as perl and print results |
568 |
<anything else> & same as above, but evaluate asynchronously |
569 |
you can use (find_coro <pid>) in perl expressions |
570 |
to find the coro with the given pid, e.g. |
571 |
(find_coro 9768720)->ready |
572 |
loglevel <int> enable logging for messages of level <int> and lower |
573 |
exit end this session |
574 |
|
575 |
Microsft victims can of course use the even less secure C<new_tcp_server> |
576 |
constructor. |
577 |
|
578 |
|
579 |
=head2 The Real World - File I/O |
580 |
|
581 |
Disk I/O, while often much faster than the network, nevertheless can take |
582 |
quite a long time in which the CPU could do other things, if one would |
583 |
only be able to do something. |
584 |
|
585 |
Fortunately, the L<IO::AIO> module on CPAN allows you to move these |
586 |
I/O calls into the background, letting you do useful work in the |
587 |
foreground. It is event-/callback-based, but Coro has a nice interface to |
588 |
it, called L<Coro::AIO>, which let's you use its functions naturally from |
589 |
within threads: |
590 |
|
591 |
use Fcntl; |
592 |
use Coro::AIO; |
593 |
|
594 |
my $fh = aio_open "$filename~", O_WRONLY | O_CREAT, 0600 |
595 |
or die "$filename~: $!"; |
596 |
|
597 |
aio_write $fh, 0, (length $data), $data, 0; |
598 |
aio_fsync $fh; |
599 |
aio_close $fh; |
600 |
aio_rename "$filename~", "$filename"; |
601 |
|
602 |
The above creates a new file, writes data into it, syncs the data to disk |
603 |
and atomically replaces a base file with a new copy. |
604 |
|
605 |
|
606 |
=head1 Other Modules |
607 |
|
608 |
This introduction only mentions a very few methods and modules, Coro has |
609 |
many other functions (see the L<Coro> manpage) and modules (documented in |
610 |
the C<SEE ALSO> section of the L<Coro> manpage). |
611 |
|
612 |
Noteworthy modules are L<Coro::LWP> (for parallel LWP requests, but see |
613 |
L<AnyEvent::HTTP> for a better HTTP-only alternative), L<Coro::BDB>, for |
614 |
when you need an asynchronous database, L<Coro::Handle>, when you need |
615 |
to use any file handle in a coroutine (popular to access C<STDIN> and |
616 |
C<STDOUT>) and L<Coro::EV>, the optimised interface to L<EV> (which gets |
617 |
used automatically by L<Coro::AnyEvent>). |
618 |
|
619 |
|
620 |
=head1 AUTHOR |
621 |
|
622 |
Marc Lehmann <schmorp@schmorp.de> |
623 |
http://home.schmorp.de/ |
624 |
|