1CALLBACK(3) Library Functions Manual CALLBACK(3)
2
6 callback - closures with variable arguments as first-class C functions
7
9 #include <callback.h>
10 void function (data, alist)
12 void* data;
13 va_alist alist;
14 {
15 va_start_type(alist[, return_type]);
16 arg = va_arg_type(alist[, arg_type]);
17 va_return_type(alist[[, return_type], return_value]);
18 }
19 callback = alloc_callback(&function, data);
21 free_callback(callback);
23 is_callback(callback)
25 callback_address(callback)
26 callback_data(callback)
27
29 These functions implement closures with variable arguments as first-
30 class C functions.
31 Closures as first-class C functions means that they fit into a function
33 pointer and can be called exactly like any other C function. Moreover,
34 they can be called with variable arguments and can return variable
35 return values.
36 callback = alloc_callback(&function, data) allocates a callback. When
38 callback gets called, it arranges to call function, passing data as
39 first argument and, as second argument, the entire sequence of argu‐
40 ments passed to callback.
41 Function calling conventions differ considerably on different machines,
43 therefore the arguments are accessed and the result value is stored
44 through the same macros as used by the vacall package, see below.
45 The callbacks are functions with indefinite extent: callback is only
47 deallocated when free_callback(callback) is called.
48 is_callback(callback) checks whether the C function callback was pro‐
50 duced by a call to alloc_callback. If this returns true, the arguments
51 given to alloc_callback can be retrieved:
52 callback_address(callback) returns &function,
54 callback_data(callback) returns data.
56
59 Within function, the following macros can be used to walk through the
60 argument list and specify a return value:
61 va_start_type(alist[, return_type]);
63 starts the walk through the argument list and specifies the
64 return type.
65 arg = va_arg_type(alist[, arg_type]);
67 fetches the next argument from the argument list.
68 va_return_type(alist[[, return_type], return_value]);
70 ends the walk through the argument list and specifies the return
71 value.
72 The type in va_start_type and va_return_type shall be one of void, int,
74 uint, long, ulong, longlong, ulonglong, double, struct, ptr or (for
75 ANSI C calling conventions only) char, schar, uchar, short, ushort,
76 float, depending on the class of return_type.
77 The type specifiers in va_start_type and va_return_type must be the
79 same. The return_type specifiers passed to va_start_type and
80 va_return_type must be the same.
81 The type in va_arg_type shall be one of int, uint, long, ulong, long‐
83 long, ulonglong, double, struct, ptr or (for ANSI C calling conventions
84 only) char, schar, uchar, short, ushort, float, depending on the class
85 of arg_type.
86 In va_start_struct(alist, return_type, splittable); the splittable flag
88 specifies whether the struct return_type can be returned in registers
89 such that every struct field fits entirely in a single register. This
90 needs to be specified for structs of size 2*sizeof(long). For structs
91 of size <= sizeof(long), splittable is ignored and assumed to be 1. For
92 structs of size > 2*sizeof(long), splittable is ignored and assumed to
93 be 0. There are some handy macros for this:
94 va_word_splittable_1 (type1)
95 va_word_splittable_2 (type1, type2)
96 va_word_splittable_3 (type1, type2, type3)
97 va_word_splittable_4 (type1, type2, type3, type4)
98 For a struct with three slots
99 struct { type1 id1; type2 id2; type3 id3; }
100 you can specify splittable as va_word_splittable_3 (type1, type2,
101 type3) .
102
105 Functions which want to emulate Kernighan & Ritchie style functions
106 (i.e., in ANSI C, functions without a typed argument list) cannot use
107 the type values char, schar, uchar, short, ushort, float. As pre‐
108 scribed by the default K&R C expression promotions, they have to use
109 int instead of char, schar, uchar, short, ushort and double instead of
110 float.
111 The macros va_start_longlong(), va_start_ulonglong(), va_return_long‐
113 long(), va_return_ulonglong(), va_arg_longlong() and va_arg_ulonglong()
114 work only if the C compiler has a working long long 64-bit integer
115 type.
116 The struct types used in va_start_struct() and va_struct() must only
118 contain (signed or unsigned) int, long, long long or pointer fields.
119 Struct types containing (signed or unsigned) char, short, float, double
120 or other structs are not supported.
121
124 vacall(3), trampoline(3).
125
128 The current implementations have been tested on a selection of common
129 cases but there are probably still many bugs.
130 There are typically built-in limits on the size of the argument-list,
132 which may also include the size of any structure arguments.
133 The decision whether a struct is to be returned in registers or in mem‐
135 ory considers only the struct's size and alignment. This is inaccurate:
136 for example, gcc on m68k-next returns struct { char a,b,c; } in regis‐
137 ters and struct { char a[3]; } in memory, although both types have the
138 same size and the same alignment.
139 <callback.h> cannot be included when <varargs.h> or <stdarg.h> is
141 included. (Name clash for va_alist.)
142 The argument list can only be walked once.
144
147 All information is passed in CPU registers and the stack. The callback
148 package is therefore multithread-safe.
149
152 Porting callback consists in first porting the vacall and trampoline
153 packages, then choosing a CPU register for passing the closure from
154 trampoline to vacall. This register is normally the register desig‐
155 nated by STATIC_CHAIN_REGNUM in the gcc source, file gcc-2.7.2/con‐
156 fig/cpu/cpu.h.
157
160 Bruno Haible <bruno@clisp.org>
161
164 Many ideas were cribbed from the gcc source.
165 14 January 2001 CALLBACK(3)