TRAMPOLINE(3)

💖 TRAMPOLINE(3) 💖

ok bestie, welcome to the Library Functions Manual page for trampoline — yes that's the manual name, and yes we're about to make closures as first-class C functions sound as cute as they actually are. ✨

---

🎀 NAME 🎀

trampoline — closures as first-class C functions 💅

---

✨ SYNOPSIS ✨

#include <trampoline.h>

function = alloc_trampoline(address, variable, data);

free_trampoline(function);

is_trampoline(function)
trampoline_address(function)
trampoline_variable(function)
trampoline_data(function)

---

🦋 DESCRIPTION 🦋

So these functions implement closures as first-class C functions. Periodt. A closure is literally just a regular C function plus a lil piece of data that gets passed to that C function whenever the closure gets called. 🫶

And when we say first-class C functions, we mean they fit into a function pointer and can be called exactly like any other C function. No special treatment, no weird ceremony. 👑

function = alloc_trampoline(address, variable, data) allocates a closure. When function gets called, it stores data in the variable variable and calls the C function at address. The function at address is responsible for fetching data out of variable immediately, before execution of any other function call. Like, before literally anything else happens. Don't be late to that party. ⏰

This is much like gcc's local functions, except that the GNU C local functions have dynamic extent (i.e. are deallocated when the creating function returns), while trampoline provides functions with indefinite extent: function is only deallocated when free_trampoline(function) is called. So it sticks around. Main character energy, honestly. 💅

is_trampoline(function) checks whether the C function function was produced by a call to alloc_trampoline. If this returns true, the arguments given to alloc_trampoline can be retrieved:

• trampoline_address(function) returns address,
• trampoline_variable(function) returns variable,
• trampoline_data(function) returns data.

---

🌈 SEE ALSO 🌈

gcc(1), stdarg(3), callback(3)

---

💀 BUGS 💀

Passing the data through a global variable is not reentrant. Not me warning you about this. 😭 Don't call trampoline functions from within signal handlers. This is fixed in the callback(3) package. 🫶

---

🧚 PORTING 🧚

The way gcc builds local functions is described in the gcc source, file gcc-2.6.3/config/cpu/cpu.h. iykyk. 📚

---

👑 AUTHOR 👑

Bruno Haible <bruno@clisp.org>

---

🌸 ACKNOWLEDGEMENTS 🌸

Many ideas were cribbed from the gcc source. Respectfully. 🙈

---

and that's a wrap, bestie 🎀 this was the TRAMPOLINE(3) page, dated 1 January 2017, and it's giving iconic. slay, stay safe, and remember to free_trampoline(function) when you're done. periodt 💖✨