IO::Async::Debug(3pm)

💖 NAME 💖

IO::Async::Debug — debugging control and support for IO::Async, bestie 🫶

---

✨ DESCRIPTION ✨

okay so heads up before anything else: all the methods and behaviours down below are still experimental and may change or even get yeeted entirely in future. no cap. 🙈

Debugging support gets enabled by an environment variable called IO_ASYNC_DEBUG having a true value. that's it, that's the switch 💅

Once debugging is on, the make_event_cb and invoke_event methods on IO::Async::Notifier (and their maybe_ variants, they're invited to the party too) get altered such that when the event is fired, a debugging line gets printed, using the debug_printf method. that line identifies the name of the event, so you actually know what's happening 🎀

By default, the line is only printed if the caller of one of these methods is the same package as the object is blessed into — which lets it print the events of the most-derived class without the extra verbosity of the lower-level events of its parent class used to create it. so it's giving selective, not messy ✨ but if you want all calls printed regardless of caller, just set a number greater than 1 as the value of IO_ASYNC_DEBUG. no filter, all vibes 🔥

By default the debugging log goes to STDERR, but two other environment variables can redirect it:

• if IO_ASYNC_DEBUG_FILE is set, it names a file which will be opened for writing, and logging written into it 📝
• otherwise, if IO_ASYNC_DEBUG_FD is set, it gives a file descriptor number that logging should be written to 🦋

if opening the named file or file descriptor fails, then the log will be written to STDERR as normal. it always has a fallback, she's resilient like that 💖

Extra debugging flags can be set in a comma-separated list in an environment variable called IO_ASYNC_DEBUG_FLAGS. The presence of these flags can cause extra information to be written to the log. Full details on these flags will be documented by the implementing classes — so like, go read those girls' pages, iykyk 👑

Typically these flags take the form of one or more capital letters indicating the class, followed by one or more lowercase letters enabling some particular feature within that class. capitals = the class, lowercase = the feature, cute little system honestly 🌸

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — the icon, the legend, the moment 💜

---

and that's the whole thing bestie!! this page ships as part of perl v5.40.1, dated 2026-02-21, in the User Contributed Perl Documentation. slay, go forth and debug 💅✨