Event(3pm)

🌸 NAME 🌸

Coro::Event — bestie, it does events the coro-way, with Event 💅

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in code, no cap:

use Coro;
use Coro::Event;

sub keyboard : Coro {
   my $w = Coro::Event->io(fd => \*STDIN, poll => 'r');
   while() {
      print "cmd> ";
      my $ev = $w->next; my $cmd = <STDIN>;
      unloop unless $cmd ne "";
      print "data> ";
      my $ev = $w->next; my $data = <STDIN>;
   }
}

loop;

# wait for input on stdin for one second
Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R
   or die "no input received";

# use a separate thread for event processing, if impossible in main:
Coro::async { Event::loop };

---

🦋 DESCRIPTION 🦋

So this module lets you build programs on top of the powerful Event model (and the module too, obviously), while keeping that linear style you already know and love from simple or threaded programs. it's giving best of both worlds fr fr 💖

For every watcher type (aka flavour) (see Event), this module hands you a method and a function. The only difference between these and the watcher constructors from Event? You don't pass a callback function — this module handles all of that for you, like a good friend should 🫶

Your app should just spin up all the threads it needs and then call Event::loop. that's it. that's the whole thing. periodt ✨

ngl, quick heads up: even programs or modules (like Coro::Handle) that use "traditional" event-based/continuation style will run more efficient with this module than when using only Event. iconic behaviour honestly 👑

---

💀 WARNING 💀

okay bestie, listen, this part is serious so no skimming 😭

Event does not support multithreading. Which means you MUST NOT block in an event callback. Again, for the people in the back: In Event callbacks, you must never ever call a Coro function that blocks the current thread. never ever. not once. not even a little 🙈

While this seems to work superficially, it will eventually cause memory corruption and often results in deadlocks. like, it'll look fine and then it will absolutely NOT be fine 💀

Best practise is to always use Coro::unblock_sub for your callbacks. do that. please. for me 🥺

---

🌈 SEMANTICS 🌈

Whenever Event blocks (e.g. in a call to one_event, loop etc.), this module cede's to all other threads with the same or higher priority.

When any threads of lower priority are ready, it will not block — instead it runs one of them, and then checks for events. lowkey genius 🧚

The effect is that coroutines with the same or higher priority than the blocking coroutine will keep Event from checking for events, while coroutines with lower priority are being run, but Event checks for new events after every cede. Note that for this to work you actually need to run the event loop in some thread. yes, actually. important detail bestie 💅

---

🎀 FUNCTIONS 🎀

• $w = Coro::Event->flavour (args...) — create and return a watcher of the given type. build-a-watcher workshop, but make it ✨efficient✨

Examples:

my $reader = Coro::Event->io (fd => $filehandle, poll => 'r');
$reader->next;

• $w->next — wait for and return the next event off the watcher's event queue. The returned event objects support two methods only: hits and got. Both of them return integers: the number this watcher was hit for this event, and the mask of poll events received. two methods, that's the whole menu 🍓
• do_flavour args... — create a watcher of the given type and immediately call its next method, returning the event. It's less efficient than calling the constructor once and the next method often, but honestly? it does save typing sometimes. and we respect that 🙈
• sweep — similar to Event::one_event and Event::sweep: the idle task is called once (which has the effect of jumping back into the Event loop once to serve new events).

The reason this function exists is that you sometimes want to serve events while doing other work. Calling Coro::cede does not work because cede implies that the current coroutine is runnable and does not call into the Event dispatcher. so like, that's why sweep is here. slay 💅

---

💌 AUTHOR/SUPPORT/CONTACT 💌

Marc A. Lehmann <schmorp@schmorp.de>
http://software.schmorp.de/pkg/Coro.html

---

and that's the whole page bestie, tysm for reading 🫶 this one's from perl v5.40.1, dated 2025-03-21 — and it's the Event(3pm) page, so now you know exactly where you are 💖✨🌸