CALLBACK(3)

💖 CALLBACK(3) — the Library Functions Manual girlies' guide to closures 💖

okay so bestie, welcome to CALLBACK(3) from the Library Functions Manual, and today we're talking about closures with variable arguments that are literally first-class C functions. yes. it's giving powerful. it's giving iconic. let's get into it 🦋

---

✨ NAME ✨

callback — closures with variable arguments as first-class C functions

---

🌸 SYNOPSIS 🌸

#include <callback.h>

void function (void* data, va_alist alist)
{
  va_start_type(alist[, return_type]);
  arg = va_arg_type(alist[, arg_type]);
  va_return_type(alist[[, return_type], return_value]);
}

callback = alloc_callback(&function, data);

free_callback(callback);

is_callback(callback)
callback_address(callback)
callback_data(callback)

---

💅 DESCRIPTION 💅

so these functions? they implement closures with variable arguments as first-class C functions. periodt.

and when we say closures as first-class C functions, we mean they fit right into a function pointer and can be called exactly like any other C function. like, no drama, no special treatment. not only that — they can be called with variable arguments and they can return variable return values. she does it all 💅

callback = alloc_callback(&function, data) allocates a callback. when callback gets called, it arranges to call function, passing data as the first argument and, as the second argument, the entire sequence of arguments passed to callback.

now here's the tea: function calling conventions differ considerably on different machines. so the arguments are accessed and the result value is stored through the same macros as used by the vacall package — see below for the whole rundown 👇

the callbacks are functions with indefinite extent: callback is only deallocated when free_callback(callback) is called. so like, she stays until you say bye. no cap.

is_callback(callback) checks whether the C function callback was produced by a call to alloc_callback. if this returns true, the arguments given to alloc_callback can be retrieved:

• callback_address(callback) returns &function,
• callback_data(callback) returns data.

---

🎀 VACALL MACROS 🎀

inside function, you can use the following macros to walk through the argument list and specify a return value:

• va_start_type(alist[, return_type]); — starts the walk through the argument list and specifies the return type.
• arg = va_arg_type(alist[, arg_type]); — fetches the next argument from the argument list.
• va_return_type(alist[[, return_type], return_value]); — ends the walk through the argument list and specifies the return value.

the type in va_start_type and va_return_type shall be one of void, int, uint, long, ulong, longlong, ulonglong, double, struct, ptr or (for ANSI C calling conventions only) char, schar, uchar, short, ushort, float, depending on the class of return_type.

the type specifiers in va_start_type and va_return_type must be the same. the return_type specifiers passed to va_start_type and va_return_type must be the same. like, they have to match, bestie, no mixing and matching 🙈

the type in va_arg_type shall be one of int, uint, long, ulong, longlong, ulonglong, double, struct, ptr or (for ANSI C calling conventions only) char, schar, uchar, short, ushort, float, depending on the class of arg_type.

in va_start_struct(alist, return_type, splittable); the splittable flag specifies whether the struct return_type can be returned in registers such that every struct field fits entirely in a single register. this needs to be specified for structs of size 2*sizeof(long). for structs of size <= sizeof(long), splittable is ignored and assumed to be 1. for structs of size > 2*sizeof(long), splittable is ignored and assumed to be 0. and there are some handy macros for this:

va_word_splittable_1 (type1)
va_word_splittable_2 (type1, type2)
va_word_splittable_3 (type1, type2, type3)
va_word_splittable_4 (type1, type2, type3, type4)

for a struct with three slots

struct { type1 id1; type2 id2; type3 id3; }

you can specify splittable as va_word_splittable_3 (type1, type2, type3).

---

🌈 NOTES 🌈

functions which want to emulate Kernighan & Ritchie style functions (i.e., in ANSI C, functions without a typed argument list) cannot use the type values char, schar, uchar, short, ushort, float. as prescribed by the default K&R C expression promotions, they have to use int instead of char, schar, uchar, short, ushort and double instead of float. them's the rules 🤷

the macros va_start_longlong(), va_start_ulonglong(), va_return_longlong(), va_return_ulonglong(), va_arg_longlong() and va_arg_ulonglong() work only if the C compiler has a working long long 64-bit integer type. if it doesn't, they simply don't work — no magic, sorry bestie 😭

the struct types used in va_start_struct() and va_struct() must only contain (signed or unsigned) int, long, long long or pointer fields. struct types containing (signed or unsigned) char, short, float, double or other structs are not supported. not supported!! 💀

---

👑 SEE ALSO 👑

vacall(3), trampoline(3).

---

💀 BUGS 💀

the current implementations have been tested on a selection of common cases but there are probably still many bugs. she's not perfect, okay, she's growing 🙈

there are typically built-in limits on the size of the argument-list, which may also include the size of any structure arguments.

the decision whether a struct is to be returned in registers or in memory considers only the struct's size and alignment. this is inaccurate: for example, gcc on m68k-next returns struct { char a,b,c; } in registers and struct { char a[3]; } in memory, although both types have the same size and the same alignment. literally the same size and alignment and yet. different outcomes. make it make sense 😭

the argument list can only be walked once.

---

⭐ NON-BUGS ⭐

all information is passed in CPU registers and the stack. the callback package is therefore multithread-safe. slay 💅

---

🧚 PORTING 🧚

porting callback consists in first porting the vacall and trampoline packages, then choosing a CPU register for passing the closure from trampoline to vacall. this register is normally the register designated by STATIC_CHAIN_REGNUM in the gcc source, file gcc-2.7.2/config/cpu/cpu.h.

---

🫶 AUTHOR 🫶

Bruno Haible <bruno@clisp.org>

---

💜 ACKNOWLEDGEMENTS 💜

many ideas were cribbed from the gcc source.

---

and that's the whole page bestie!! you ate that. go forth and allocate those callbacks responsibly 🎀

okay so final sign-off: this whole thing is dated 1 January 2017, and it's CALLBACK(3) — yes, that very same section you started at the top. full circle, iconic, bye 💖