1Intro(3) User Contributed Perl Documentation Intro(3)
2
6 This tutorial will introduce you to the main features of the Coro
7 module family.
8 It first introduces some basic concepts, and later gives a short
10 overview of the module family.
11
13 Coro started as a simple module that implemented a specific form of
14 first class continuations called Coroutines. These basically allow you
15 to capture the current point execution and jump to another point, while
16 allowing you to return at any time, as kind of non-local jump, not
17 unlike C's "setjmp"/"longjmp". This is nowadays known as a Coro::State.
18 One natural application for these is to include a scheduler, resulting
20 in cooperative threads, which is the main use case for Coro today.
21 Still, much of the documentation and custom refers to these threads as
22 "coroutines" or often just "coros".
23 A thread is very much like a stripped-down perl interpreter, or a
25 process: Unlike a full interpreter process, a thread doesn't have its
26 own variable or code namespaces - everything is shared. That means that
27 when one thread modifies a variable (or any value, e.g. through a
28 reference), then other threads immediately see this change when they
29 look at the same variable or location.
30 Cooperative means that these threads must cooperate with each other,
32 when it comes to CPU usage - only one thread ever has the CPU, and if
33 another thread wants the CPU, the running thread has to give it up. The
34 latter is either explicitly, by calling a function to do so, or
35 implicitly, when waiting on a resource (such as a Semaphore, or the
36 completion of some I/O request). This threading model is popular in
37 scripting languages (such as python or ruby), and this implementation
38 is typically far more efficient than threads implemented in other
39 languages.
40 Perl itself uses rather confusing terminilogy - what perl calls a
42 "thread" (or "ithread") is actually called a "process" everywhere else:
43 The so-called "perl threads" are actually artifacts of the unix process
44 emulation code used on Windows, which is consequently why they are
45 actually processes and not threads. The biggest difference is that
46 neither variables (nor code) are shared between processes or ithreads.
47
49 Cooperative threads is what the Coro module gives you. Obviously, you
50 have to "use" it first:
51 use Coro;
53 To create a thread, you can use the "async" function that automatically
55 gets exported from that module:
56 async {
58 print "hello\n";
59 };
60 Async expects a code block as first argument (in indirect object
62 notation). You can actually pass it extra arguments, and these will end
63 up in @_ when executing the codeblock, but since it is a closure, you
64 can also just refer to any lexical variables that are currently
65 visible.
66 The above lines create a thread, but if you save them in a file and
68 execute it as a perl program, you will not get any output.
69 The reasons is that, although you created a thread, and the thread is
71 ready to execute (because "async" puts it into the so-called ready
72 queue), it never gets any CPU time to actually execute, as the main
73 program - which also is a thread almost like any other - never gives up
74 the CPU but instead exits the whole program, by running off the end of
75 the file. Since Coro threads are cooperative, the main thread has to
76 cooperate, and give up the CPU.
77 To explicitly give up the CPU, use the "cede" function (which is often
79 called "yield" in other thread implementations):
80 use Coro;
82 async {
84 print "hello\n";
85 };
86 cede;
88 Running the above prints "hello" and exits.
90 Now, this is not very interesting, so let's try a slightly more
92 interesting program:
93 use Coro;
95 async {
97 print "async 1\n";
98 cede;
99 print "async 2\n";
100 };
101 print "main 1\n";
103 cede;
104 print "main 2\n";
105 cede;
106 Running this program prints:
108 main 1
110 async 1
111 main 2
112 async 2
113 This nicely illustrates the non-local jump ability: the main program
115 prints the first line, and then yields the CPU to whatever other
116 threads there are. And there is one other, which runs and prints "async
117 1", and itself yields the CPU. Since the only other thread available is
118 the main program, it continues running and so on.
119 Let's look at the example in more detail: "async" first creates a new
121 thread. All new threads start in a suspended state. To make them run,
122 they need to be put into the ready queue, which is the second thing
123 that "async" does. Each time a thread gives up the CPU, Coro runs a so-
124 called scheduler. The scheduler selects the next thread from the ready
125 queue, removes it from the queue, and runs it.
126 "cede" also does two things: first it puts the running thread into the
128 ready queue, and then it jumps into the scheduler. This has the effect
129 of giving up the CPU, but also ensures that, eventually, the thread
130 gets run again.
131 In fact, "cede" could be implemented like this:
133 sub my_cede {
135 $Coro::current->ready;
136 schedule;
137 }
138 This works because $Coro::current always contains the currently running
140 thread, and the scheduler itself can be called directly via
141 "Coro::schedule".
142 What is the effect of just calling "schedule" without putting the
144 current thread into the ready queue first? Simple: the scheduler
145 selects the next ready thread and runs it. And the current thread, as
146 it hasn't been put into the ready queue, will go to sleep until
147 something wakes it up. If. Ever.
148 The following example remembers the current thread in a variable,
150 creates a thread and then puts the main program to sleep.
151 The newly created thread uses rand to wake up the main thread by
153 calling its "ready" method - or not.
154 use Coro;
156 my $wakeme = $Coro::current;
158 async {
160 $wakeme->ready if 0.5 > rand;
161 };
162 schedule;
164 Now, when you run it, one of two things happen: Either the "async"
166 thread wakes up the main thread again, in which case the program
167 silently exits, or it doesn't, in which case you get something like
168 this:
169 FATAL: deadlock detected.
171 PID SC RSS USES Description Where
172 31976480 -C 19k 0 [main::] [program:9]
173 32223768 UC 12k 1 [Coro.pm:691]
174 32225088 -- 2068 1 [coro manager] [Coro.pm:691]
175 32225184 N- 216 0 [unblock_sub scheduler] -
176 Why is that? Well, when the "async" thread runs into the end of its
178 block, it will be terminated (via a call to "Coro::terminate") and the
179 scheduler is called again. Since the "async" thread hasn't woken up the
180 main thread, and there aren't any other threads, there is nothing to
181 wake up, and the program cannot continue. Since there are threads that
182 could be running (main) but none are ready to do so, Coro signals a
183 deadlock - no progress is possible. Usually you also get a listing of
184 all threads, which might help you track down the problem.
185 However, there is an important case where progress is, in fact,
187 possible, despite no threads being ready - namely in an event-based
188 program. In such a program, some threads could wait for external
189 events, such as a timeout, or some data to arrive on a socket.
190 Since a deadlock in such a case would not be very useful, there is a
192 module named Coro::AnyEvent that integrates threads into an event loop.
193 It configures Coro in a way that, instead of "die"ing with an error
194 message, it instead runs the event loop in the hope of receiving an
195 event that will wake up some thread.
196 Semaphores and other locks
198 Using only "ready", "cede" and "schedule" to synchronise threads is
199 difficult, especially if many threads are ready at the same time. Coro
200 supports a number of primitives to help synchronising threads in easier
201 ways. The first such primitives is Coro::Semaphore, which implements
202 counting semaphores (binary semaphores are available as Coro::Signal,
203 and there are Coro::SemaphoreSet and Coro::RWLock primitives as well).
204 Counting semaphores, in a sense, store a count of resources. You can
206 remove/allocate/reserve a resource by calling the "->down" method,
207 which decrements the counter, and you can add or free a resource by
208 calling the "->up" method, which increments the counter. If the counter
209 is 0, then "->down" cannot decrement the semaphore - it is locked - and
210 the thread will wait until a count becomes available again.
211 Here is an example:
213 use Coro;
215 my $sem = new Coro::Semaphore 0; # a locked semaphore
217 async {
219 print "unlocking semaphore\n";
220 $sem->up;
221 };
222 print "trying to lock semaphore\n";
224 $sem->down;
225 print "we got it!\n";
226 This program creates a locked semaphore (a semaphore with count 0) and
228 tries to lock it (by trying to decrement it's counter in the "down"
229 method). Since the semaphore count is already exhausted, this will
230 block the main thread until the semaphore becomes available.
231 This yields the CPU to the only other read thread in the process,t he
233 one created with "async", which unlocks the semaphore (and instantly
234 terminates itself by returning).
235 Since the semaphore is now available, the main program locks it and
237 continues: "we got it!".
238 Counting semaphores are most often used to lock resources, or to
240 exclude other threads from accessing or using a resource. For example,
241 consider a very costly function (that temporarily allocates a lot of
242 ram, for example). You wouldn't want to have many threads calling this
243 function at the same time, so you use a semaphore:
244 my $lock = new Coro::Semaphore; # unlocked initially - default is 1
246 sub costly_function {
248 $lock->down; # acquire semaphore
249 # do costly operation that blocks
251 $lock->up; # unlock it
253 }
254 No matter how many threads call "costly_function", only one will run
256 the body of it, all others will wait in the "down" call. If you want to
257 limit the number of concurrent executions to five, you could create the
258 semaphore with an initial count of 5.
259 Why does the comment mention an "operation the blocks"? Again, that's
261 because coro's threads are cooperative: unless "costly_function"
262 willingly gives up the CPU, other threads of control will simply not
263 run. This makes locking superfluous in cases where the function itself
264 never gives up the CPU, but when dealing with the outside world, this
265 is rare.
266 Now consider what happens when the code "die"s after executing "down",
268 but before "up". This will leave the semaphore in a locked state, which
269 often isn't what you want - imagine the caller expecting a failure and
270 wrapping the call into an "eval {}".
271 So normally you would want to free the lock again if execution somehow
273 leaves the function, whether "normally" or via an exception. Here the
274 "guard" method proves useful:
275 my $lock = new Coro::Semaphore; # unlocked initially
277 sub costly_function {
279 my $guard = $lock->guard; # acquire guard
280 # do costly operation that blocks
282 }
283 The "guard" method "down"s the semaphore and returns a so-called guard
285 object. Nothing happens as long as there are references to it (i.e. it
286 is in scope somehow), but when all references are gone, for example,
287 when "costly_function" returns or throws an exception, it will
288 automatically call "up" on the semaphore, no way to forget it. Even
289 when the thread gets "cancel"ed by another thread will the guard object
290 ensure that the lock is freed.
291 This concludes this introduction to semaphores and locks. Apart from
293 Coro::Semaphore and Coro::Signal, there is also a reader-writer lock
294 (Coro::RWLock) and a semaphore set (Coro::SemaphoreSet). All of these
295 come with their own manpage.
296 Channels
298 Semaphores are fine, but usually you want to communicate by exchanging
299 data as well. Of course, you can just use some locks, and array of
300 sorts and use that to communicate, but there is a useful abstraction
301 for communicaiton between threads: Coro::Channel. Channels are the Coro
302 equivalent of a unix pipe (and very similar to AmigaOS message ports :)
303 - you can put stuff into it on one side, and read data from it on the
304 other.
305 Here is a simple example that creates a thread and sends numbers to it.
307 The thread calculates the square of each number and puts that into
308 another channel, which the main thread reads the result from:
309 use Coro;
311 my $calculate = new Coro::Channel;
313 my $result = new Coro::Channel;
314 async {
316 # endless loop
317 while () {
318 my $num = $calculate->get; # read a number
319 $num **= 2; # square it
320 $result->put ($num); # put the result into the result queue
321 }
322 };
323 for (1, 2, 5, 10, 77) {
325 $calculate->put ($_);
326 print "$_ ** 2 = ", $result->get, "\n";
327 }
328 Gives:
330 1 ** 2 = 1
332 2 ** 2 = 4
333 5 ** 2 = 25
334 10 ** 2 = 100
335 77 ** 2 = 5929
336 Both "get" and "put" methods can block the current thread: "get" first
338 checks whether there is some data available, and if not, it block the
339 current thread until some data arrives. "put" can also block, as each
340 Channel has a "maximum item capacity", i.e. you cannot store more than
341 a specific number of items, which can be configured when the Channel
342 gets created.
343 In the above example, "put" never blocks, as the default capacity of a
345 Channel is very high. So the for loop first puts data into the channel,
346 then tries to "get" the result. Since the async thread hasn't put
347 anything in there yet (on the first iteration it hasn't even run yet),
348 the result Channel is still empty, so the main thread blocks.
349 Since the only other runnable/ready thread at this point is the
351 squaring thread, it will be woken up, will "get" the number, square it
352 and put it into the result channel, waking up the main thread again. It
353 will still continue to run, as waking up other threads just puts them
354 into the ready queue, nothing less, nothing more.
355 Only when the async thread tries to "get" the next number from the
357 calculate channel will it block (because nothing is there yet) and the
358 main thread will continue running. And so on.
359 This illustrates a general principle used by Coro: a thread will only
361 ever block when it has to. Neither the Coro module itself nor any of
362 its submodules will ever give up the CPU unless they have to, because
363 they wait for some event to happen.
364 Be careful, however: when multiple threads put numbers into $calculate
366 and read from $result, they won't know which result is theirs. The
367 solution for this is to either use a semaphore, or send not just the
368 number, but also your own private result channel.
369 What is mine, what is ours?
371 What, exactly, constitutes a thread? Obviously it contains the current
372 point of execution. Not so obviously, it also has to include all
373 lexical variables, that means, every thread has its own set of lexical
374 variables.
375 To see why this is necessary, consider this program:
377 use Coro;
379 sub printit {
381 my ($string) = @_;
382 cede;
384 print $string;
386 }
387 async { printit "Hello, " };
389 async { printit "World!\n" };
390 cede; cede; # do it
392 The above prints "Hello, World!\n". If "printit" wouldn't have its own
394 per-thread $string variable, it would probably print "World!\nWorld\n",
395 which is rather unexpected, and would make it very difficult to make
396 good use of threads.
397 To make things run smoothly, there are quite a number of other things
399 that are per-thread:
400 $_, @_, $@ and the regex result vars, $&, %+, $1, $2, ...
402 $_ is used much like a local variable, so it gets localised per-
403 thread. The same is true for regex results ($1, $2 and so on).
404 @_ contains the arguments, so like lexicals, it also must be per-
406 thread.
407 $@ is not obviously required to be per-thread, but it is quite
409 useful.
410 $/ and the default output file handle
412 Threads most often block when doing I/O. Since $/ is used when
413 reading lines, it would be very inconvenient if it were a shared
414 variable, so it is per-thread.
415 The default output handle (see "select") is a difficult case:
417 sometimes being global is preferable, sometimes per-thread is
418 preferable. Since per-thread seems to be more common, it is per-
419 thread.
420 $SIG{__DIE__} and $SIG{__WARN__}
422 If these weren't per-thread, then common constructs such as:
423 eval {
425 local $SIG{__DIE__} = sub { ... };
426 ...
427 };
428 Would not allow coroutine switching. Since exception-handling is
430 per-thread, those variables should be per-thread as well.
431 Lots of other esoteric stuff
433 For example, $^H is per-thread. Most of the additional per-thread
434 state is not directly visible to Perl, but required to make the
435 interpreter work. You won't normally notice these.
436 Everything else is shared between all threads. For example, the globals
438 $a and $b are shared. When does that matter? When using "sort", these
439 variables become special, and therefore, switching threads when sorting
440 might have surprising results.
441 Other examples are the $!, errno, $., the current input line number,
443 $,, "$\", $" and many other special variables.
444 While in some cases a good argument could be made for localising them
446 to the thread, they are rarely used, and sometimes hard to localise.
447 Future versions of Coro might include more per-thread state when it
449 becomes a problem.
450 Debugging
452 Sometimes it can be useful to find out what each thread is doing (or
453 which threads exist in the first place). The Coro::Debug module has
454 (among other goodies), a function that allows you to print a "ps"-like
455 listing - you have seen it in action earlier when Coro detected a
456 deadlock.
457 You use it like this:
459 use Coro::Debug;
461 Coro::Debug::command "ps";
463 Remember the example with the two channels and a worker thread that
465 squared numbers? Running "ps" just after "$calculate->get" outputs
466 something similar to this:
467 PID SC RSS USES Description Where
469 8917312 -C 22k 0 [main::] [introscript:20]
470 8964448 N- 152 0 [coro manager] -
471 8964520 N- 152 0 [unblock_sub scheduler] -
472 8591752 UC 152 1 [introscript:12]
473 11546944 N- 152 0 [EV idle process] -
474 Interesting - there is more going on in the background than one would
476 expect. Ignoring the extra threads, the main thread has pid 8917312,
477 and the one started by "async" has pid 8591752.
478 The latter is also the only thread that doesn't have a description,
480 simply because we haven't set one. Setting one is easy, just put it
481 into "$Coro::current->{desc}":
482 async {
484 $Coro::current->{desc} = "cruncher";
485 ...
486 };
487 This can be rather useful when debugging a program, or when using the
489 interactive debug shell of Coro::Debug.
490
492 Coro really wants to run in a program using some event loop. In fact,
493 most real-world programs using Coro threads are written with a
494 combination of event-based and thread-based techniques, as it is easy
495 to get the best of both worlds with Coro.
496 Coro integrates automatically into any event loop supported by AnyEvent
498 (see Coro::AnyEvent for details), but can take special advantage of the
499 EV and Event modules.
500 Here is a simple finger client, using whatever event loop AnyEvent
502 comes up with:
503 use Coro;
505 use Coro::Socket;
506 sub finger {
508 my ($user, $host) = @_;
509 my $fh = new Coro::Socket PeerHost => $host, PeerPort => "finger"
511 or die "$user\@$host: $!";
512 print $fh "$user\n";
514 print "$user\@$host: $_" while <$fh>;
516 print "$user\@$host: done\n";
517 }
518 # now finger a few accounts
520 for (
521 (async { finger "abc", "cornell.edu" }),
522 (async { finger "sebbo", "world.std.com" }),
523 (async { finger "trouble", "noc.dfn.de" }),
524 ) {
525 $_->join; # wait for the result
526 }
527 There are a few new things here. First of all, there is Coro::Socket.
529 This module works much the same way as IO::Socket::INET, except that it
530 is coroutine-aware. This means that IO::Socket::INET, when waiting for
531 the network, will block the whole process - that means all threads,
532 which is clearly undesirable.
533 On the other hand, Coro::Socket knows how to give up the CPU to other
535 threads when it waits for the network, which makes parallel execution
536 possible.
537 The other new thing is the "join" method: All we want to do in this
539 example is start three "async" threads and only exit when they have
540 done their job. This could be done using a counting semaphore, but it
541 is much simpler to synchronously wait for them to "terminate", which is
542 exactly what the "join" method does.
543 It doesn't matter that the three "async"s will probably finish in a
545 different order then the for loop "join"s them - when the thread is
546 still running, "join" simply waits. If the thread has already
547 terminated, it will simply fetch its return status.
548 If you are experienced in event-based programming, you will see that
550 the above program doesn't quite follow the normal pattern, where you
551 start some work, and then run the event loop (e.v. "EV::loop").
552 In fact, nontrivial programs follow this pattern even with Coro, so a
554 Coro program that uses EV usually looks like this:
555 use EV;
557 use Coro;
558 # start coroutines or event watchers
560 EV::loop; # and loop
562 And in fact, for debugging, you often do something like this:
564 use EV;
566 use Coro::Debug;
567 my $shell = new_unix_server Coro::Debug "/tmp/myshell";
569 EV::loop; # and loop
571 This runs your program, but also an interactive shell on the unix
573 domain socket in /tmp/myshell. You can use the socat program to access
574 it:
575 # socat readline /tmp/myshell
577 coro debug session. use help for more info
578 > ps
580 PID SC RSS USES Description Where
581 136672312 RC 19k 177k [main::] [myprog:28]
582 136710424 -- 1268 48 [coro manager] [Coro.pm:349]
583 > help
584 ps [w|v] show the list of all coroutines (wide, verbose)
585 bt <pid> show a full backtrace of coroutine <pid>
586 eval <pid> <perl> evaluate <perl> expression in context of <pid>
587 trace <pid> enable tracing for this coroutine
588 untrace <pid> disable tracing for this coroutine
589 kill <pid> <reason> throws the given <reason> string in <pid>
590 cancel <pid> cancels this coroutine
591 ready <pid> force <pid> into the ready queue
592 <anything else> evaluate as perl and print results
593 <anything else> & same as above, but evaluate asynchronously
594 you can use (find_coro <pid>) in perl expressions
595 to find the coro with the given pid, e.g.
596 (find_coro 9768720)->ready
597 loglevel <int> enable logging for messages of level <int> and lower
598 exit end this session
599 Microsft victims can of course use the even less secure
601 "new_tcp_server" constructor.
602 The Real World - File I/O
604 Disk I/O, while often much faster than the network, nevertheless can
605 take quite a long time in which the CPU could do other things, if one
606 would only be able to do something.
607 Fortunately, the IO::AIO module on CPAN allows you to move these I/O
609 calls into the background, letting you do useful work in the
610 foreground. It is event-/callback-based, but Coro has a nice wrapper
611 around it, called Coro::AIO, which lets you use its functions naturally
612 from within threads:
613 use Fcntl;
615 use Coro::AIO;
616 my $fh = aio_open "$filename~", O_WRONLY | O_CREAT, 0600
618 or die "$filename~: $!";
619 aio_write $fh, 0, (length $data), $data, 0;
621 aio_fsync $fh;
622 aio_close $fh;
623 aio_rename "$filename~", "$filename";
624 The above creates a new file, writes data into it, syncs the data to
626 disk and atomically replaces a base file with a new copy.
627 Inversion of control - rouse functions
629 Last not least, me talk about inversion of control. The "control"
630 refers to "who calls whom", who is in control of the program. In this
631 program, the main program is in control and passes this to all
632 functions it calls:
633 use LWP;
635 # pass control to get
637 my $res = get "http://example.org/";
638 # control returned to us
639 print $res;
641 When switching to event-based programs, instead of "us calling them",
643 "they call us" - this is the inversion of control form the title:
644 use AnyEvent::HTTP;
646 # do not pass control for long - http_get immediately returns
648 http_get "http://example.org/", sub {
649 print $_[0];
650 };
651 # we stay in control and can do other things
653 Event based programming can be nice, but sometimes it's just easier to
655 write down some processing in "linear" fashion, without callbacks. Coro
656 provides some special functions to reduce typing:
657 use AnyEvent::HTTP;
659 # do not pass control for long - http_get immediately returns
661 http_get "http://example.org/", Coro::rouse_cb;
662 # we stay in control and can do other things...
664 # ...such as wait for the result
665 my ($res) = Coro::rouse_wait;
666 "Coro::rouse_cb" creates and returns a special callback. You can pass
668 this callback to any function that would expect a callback.
669 "Coro::rouse_wait" waits (block the current thread) until the most
671 recently created callback has been called, and returns whatever was
672 passed to it.
673 These two functions allow you to mechanically invert the control from
675 "callback based style" used by most event-based libraries to "blocking
676 style", whenever you wish to.
677 The pattern is simple: instead of...
679 some_func ..., sub {
681 my @res = @_;
682 ...
683 };
684 ... you write:
686 some_func ..., Coro::rouse_cb;
688 my @res = Coro::rouse_wait;
689 ...
690 Callback-based interfaces are plenty, and the rouse functions allow you
692 to use them in an often more convenient way.
693
695 This introduction only mentions a few methods and modules, Coro has
696 many other functions (see the Coro manpage) and modules (documented in
697 the "SEE ALSO" section of the Coro manpage).
698 Noteworthy modules are Coro::LWP (for parallel LWP requests, but see
700 AnyEvent::HTTP for a better HTTP-only alternative), Coro::BDB, for when
701 you need an asynchronous database, Coro::Handle, when you need to use
702 any file handle in a coroutine (popular to access "STDIN" and "STDOUT")
703 and Coro::EV, the optimised interface to EV (which gets used
704 automatically by Coro::AnyEvent).
705 There are a number of Coro-related moduels that might be useful for
707 your problem (see
708 <http://search.cpan.org/search?query=Coro&mode=module>). And since Coro
709 integrates so well into AnyEvent, it's often easy to adapt existing
710 AnyEvent modules (see
711 <http://search.cpan.org/search?query=AnyEvent&mode=module>).
712
714 Marc Lehmann <schmorp@schmorp.de>
715 http://home.schmorp.de/
716perl v5.36.0 2022-07-22 Intro(3)