PCRE_ASSIGN_JIT_STACK(3)

💖 PCRE_ASSIGN_JIT_STACK 💖

okay bestie, so this page is literally all about PCRE — that's Perl-compatible regular expressions — and specifically the pcre_assign_jit_stack function. it's a Library Functions Manual situation, and honestly? it's giving "i control the vibes of your regex memory" energy. 🦋

✨ SYNOPSIS ✨

here's the tea, copy-pasted with love:

#include <pcre.h>

void pcre_assign_jit_stack(pcre_extra *extra,
     pcre_jit_callback callback, void *data);

void pcre16_assign_jit_stack(pcre16_extra *extra,
     pcre16_jit_callback callback, void *data);

void pcre32_assign_jit_stack(pcre32_extra *extra,
     pcre32_jit_callback callback, void *data);

yes there are three of them (8-bit, 16-bit, 32-bit, the whole girl group 💅) and yes they all do the same thing. periodt.

🌸 DESCRIPTION 🌸

so like. this function gives you control over the memory used as a stack at run-time when you call pcre[16|32]_exec() on a pattern that's been successfully compiled with JIT optimization. iykyk — JIT means just-in-time, and it needs a stack, and this is where you get to pick which one. 👑

the arguments are:

• extra — the data pointer returned by pcre[16|32]_study()
• callback — a callback function
• data — a JIT stack or a value to be passed to the callback function

🎀 the vibe check: what actually happens

there's basically a little flowchart and honestly it ate:

• If callback is NULL and data is NULL, an internal 32K block on the machine stack is used. easy, no thoughts, default behavior.
• If callback is NULL and data is not NULL, then data must be a valid JIT stack — the result of calling pcre[16|32]_jit_stack_alloc(). no fake stacks bestie, it has to be the real thing.
• If callback is not NULL, it is called with data as an argument at the start of matching, in order to set up a JIT stack. if the result is NULL, the internal 32K stack is used; otherwise the return value must be a valid JIT stack, the result of calling pcre[16|32]_jit_stack_alloc(). 🫶

🧚 threads, bestie, please listen

You may safely assign the same JIT stack to multiple patterns, as long as they are all matched in the same thread. 🧵

In a multithread application, each thread must use its own JIT stack. no sharing, no borrowing, no "it's fine" — it is not fine. 🙈

For more details, see the pcrejit page. it's the deep dive if you want it.

🌈 where to learn more

There is a complete description of the PCRE native API in the pcreapi page and a description of the POSIX API in the pcreposix page. go read those, they're iconic. ⭐

ngl the whole thing is: pick your stack, don't cross the threads, and make sure any stack you hand over actually came from pcre[16|32]_jit_stack_alloc(). that's the whole assignment. 💀

and that's the page!! this one's from PCRE 8.30, dated 24 June 2012 — yeah she's vintage but she's still slaying 💜 bye bestie, go allocate responsibly 🎀✨