PERLMULTICORE.H(1)

💖 PERLMULTICORE.H 💖

okay bestie, so this is a page from the User Contributed Perl Documentation corner of the manual, and it's all about perlmulticore.h — the lil header file that implements the Perl Multicore Specification. literally so iconic of it. ✨

---

🌸 NAME 🌸

perlmulticore.h — implements the Perl Multicore Specification 🧚

---

✨ SYNOPSIS ✨

#include "perlmulticore.h"

// in your XS function:

perlinterp_release ();
do_the_C_thing ();
perlinterp_acquire ();

// optional, in BOOT section:

perlmulticore_support ();

---

🦋 DESCRIPTION 🦋

real talk: this doc right here is the abridged version of the full documentation over at http://perlmulticore.schmorp.de/. they straight-up recommend you go read that one instead of this one. no shade to this one, but okay. 💅

so what does this header file do? it implements a very low overhead mechanism — lowkey in code AND highkey in runtime — that lets XS modules allow the perl interpreter to be re-used by other threads while you're off doing some lengthy operation. we're talking cryptography, SQL queries, disk I/O, that whole vibe. 🔥

and the newest version of the header file itself? you can download it from http://perlmulticore.schmorp.de/perlmulticore.h. periodt.

---

🎀 HOW DO I USE THIS IN MY MODULES? 🎀

the usage is very simple, bestie — you include this header file in your XS module. then, before you do your lengthy operation, you release the perl interpreter:

perlinterp_release ();

and when you're done with your computation, you acquire it again:

perlinterp_acquire ();

and that's it. that's the whole thing. 🫶 it doesn't load any modules, and when no module that takes advantage of it is loaded, it's literally just a few machine instructions. the way that it costs nothing… obsessed.

more documentation and examples can be found at the perl multicore site at http://perlmulticore.schmorp.de.

---

👑 THE HARD AND FAST RULES 👑

as with everything, there are a number of rules to follow. don't skip these, they're not optional, they're the vibe check you must pass. ⭐

• Never touch any perl data structures after calling perlinterp_release.

anything perl is completely off-limits after perlinterp_release, until you call perlinterp_acquire, after which you can access perl stuff again. 💜

that includes anything in the perl interpreter that you didn't prove to be safe, and didn't prove to be safe in older and future versions of perl: global variables, local perl scalars — even if you are sure nobody accesses them and you only try to "read" their value. yeah, not even a little peek. 🙈

• Always call perlinterp_release and perlinterp_acquire in pairs.

for each perlinterp_release call there must be a perlinterp_acquire call. they don't have to be in the same function, and you can have multiple calls to them, as long as every perlinterp_release call is followed by exactly one perlinterp_acquire call at runtime. matching set, no cap. ✨

• Never nest calls to perlinterp_release and perlinterp_acquire.

that simply means that after calling perlinterp_release, you must call perlinterp_acquire before calling perlinterp_release again. likewise, after perlinterp_acquire, you can call perlinterp_release but not another perlinterp_acquire. no stacking, babe. 💅

• Always call perlinterp_release first.

you must not call perlinterp_acquire without having called perlinterp_release before. order matters, main character energy only. 👑

• Never underestimate threads.

while it's easy to add parallel execution ability to your XS module, it doesn't mean it is safe. after you release the perl interpreter, it's perfectly possible that it will call your XS function in another thread, even while your original function still executes. in other words: your C code must be thread safe, and if you use any library, that library must be thread-safe, too. 😭

always assume that the code between perlinterp_release and perlinterp_acquire is executed in parallel on multiple CPUs at the same time. fr fr. 🔥

---

🌈 DISABLING PERL MULTICORE AT COMPILE TIME 🌈

you can disable the complete perl multicore API by defining the symbol PERL_MULTICORE_DISABLE to 1 — like, e.g. by specifying -DPERL_MULTICORE_DISABLE as compiler argument. 🛠️

this could be added to perl's CPPFLAGS when configuring perl on platforms that do not support threading at all, for example. iykyk.

---

🍓 ADVERTISING MULTICORE API SUPPORT 🍓

to help users find out whether a particular build of your module is, in fact, multicore enabled, you can invoke the perlmulticore_support macro in your BOOT: section, e.g.:

MODULE = My::Mod    PACKAGE = My::Mod::Pkg

BOOT:
   perlmulticore_support ();

what this does is set the $My::Mod::PERLMULTICORE_SUPPORT variable to the major API version * 1000 + minor version — for example, version 1002 introduced this feature. slay. ✨

for this to work, the cv parameter passed to BOOT: must still be in scope. to ensure this, either invoke the macro early in your BOOT: section, or don't declare a local variable called cv — either of which should be easy to do. 🧚

note that this is optional, so you don't have to do that. no pressure, bestie. 💖

---

💜 AUTHOR 💜

Marc A. Lehmann <perlmulticore@schmorp.de>
http://perlmulticore.schmorp.de/

---

💀 LICENSE 💀

the perlmulticore.h header file is put into the public domain. where this is legally not possible, or at your option, it can be licensed under creativecommons CC0 license: https://creativecommons.org/publicdomain/zero/1.0/.

---

okay and that's the whole page!! 🎀 one last thing — this little cutie comes to you from perl v5.42.0, dated 2025-07-25, and it's filed under PERLMULTICORE.H(1) in the manual. mwah. 💅🌸💖