MakeMaker(3pm)

✨ NAME ✨

Coro::MakeMaker — the MakeMaker glue that lets you vibe with the XS-level Coro API 💖

(also this page lives in section 3pm, aka User Contributed Perl Documentation, iykyk)

---

🌸 SYNOPSIS 🌸

This lets you control coroutines straight from C/XS. Yes, from C. Main character energy fr fr.

---

🦋 DESCRIPTION 🦋

Okay so bestie, if you want optimal performance, you gotta hook into Coro at the C-level. That means you're gonna:

• make some changes to your Makefile.PL, and
• add code to your xs / c file(s)

That's the whole deal. Let's go. ✨

---

💀 WARNING 💀

When you hook in at the C-level you can get a huge performance gain, but you also reduce the chances that your code will work unmodified with newer versions of perl or Coro. This may or may not be a problem. Just be aware, and set your expectations accordingly.

Not me telling you this is lowkey a situationship with your future perl upgrade 😭 Like yes, the speed is giving, but the portability is not. Go in with your eyes open, bestie. 💅

---

🎀 HOW TO 🎀

🌟 Makefile.PL 🌟

Do it like this:

  use Coro::MakeMaker qw(coro_args);

  # ... set up %args ...

  WriteMakefile (coro_args (%args));

💜 XS 💜

And in your XS file:

  #include "CoroAPI.h"

  BOOT:
    I_CORO_API ("YourModule");

🧚 API 🧚

This is just a small overview — read the Coro/CoroAPI.h header file in the distribution, and check the examples in EV/ and Event/*, or as a more real-world example, the Deliantra game server (which uses Coro::MakeMaker). 🔥

You can also drop me a mail if you run into any trouble. 🫶

  #define CORO_TRANSFER(prev,next) /* transfer from prev to next */
  #define CORO_SCHEDULE            /* like Coro::schedule */
  #define CORO_CEDE                /* like Coro::cede */
  #define CORO_CEDE_NOTSELF        /* like Coro::cede_notself */
  #define CORO_READY(coro)         /* like $coro->ready */
  #define CORO_IS_READY(coro)      /* like $coro->is_ready */
  #define CORO_NREADY              /* # of procs in ready queue */
  #define CORO_CURRENT             /* returns $Coro::current */
  #define CORO_THROW               /* exception pending? */
  #define CORO_READYHOOK           /* hook for event libs, see Coro::EV */

  /* C-level coroutine struct, opaque, not used much */
  struct coro;

  /* used for schedule-like-function prepares */
  struct coro_transfer_args
  {
    struct coro *prev, *next;
  };

  /* this is the per-perl-coro slf frame info */
  struct CoroSLF
  {
    void (*prepare) (pTHX_ struct coro_transfer_args *ta); /* 0 means not yet initialised */
    int (*check) (pTHX_ struct CoroSLF *frame);
    void *data; /* for use by prepare/check/destroy */
    void (*destroy) (pTHX_ struct CoroSLF *frame);
  };

  /* needs to fill in the *frame */
  typedef void (*coro_slf_cb) (pTHX_ struct CoroSLF *frame, CV *cv, SV **arg, int items);

  #define CORO_SV_STATE(coro)      /* returns the internal struct coro * */
  #define CORO_EXECUTE_SLF(cv,init,ax) /* execute a schedule-like function */
  #define CORO_EXECUTE_SLF_XS(init) /* SLF in XS, see e.g. Coro::EV */

  /* called on enter/leave */
  typedef void (*coro_enterleave_hook) (pTHX_ void *arg);

  #define CORO_ENTERLEAVE_HOOK(coro,enter,enter_arg,leave,leave_arg)   /* install an XS-level enter/leave hook */
  #define CORO_ENTERLEAVE_UNHOOK(coro,enter,leave)                     /* remove an XS-level enter/leave hook */
  #define CORO_ENTERLEAVE_SCOPE_HOOK(enter,enter_arg,leave,leave_arg)  /* install an XS-level enter/leave hook for the corrent scope */

Not me spotting that the last one says corrent scope instead of "current" 🙈 bestie that's exactly how it's written in the source, so we keep it, no cap. Copy it verbatim or your build will simply not eat. 💅

---

👑 AUTHOR/SUPPORT/CONTACT 👑

The one and only, the icon, the blueprint:

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

---

And that's the whole page, bestie! 🎀 This lil' cutie is from perl v5.40.1, dated 2025-03-21, and it's filed under MakeMaker(3pm). Slay, go write some XS, and hydrate. ✨💖🦋