1
.TH CALLBACK 3 "14 January 2001"
3
callback \- closures with variable arguments as first-class C functions
5
.B #include <callback.h>
8
.BI "void " function " (" data ", " alist ")"
10
.BI " va_alist " alist ";"
12
.BI " va_start_" type "(" alist "[, " return_type "]);"
13
.BI " " arg " = va_arg_" type "(" alist "[, " arg_type "]);"
14
.BI " va_return_" type "(" alist "[[, " return_type "], " return_value "]);"
18
.IB callback " = alloc_callback(" "&function" ", " data ");"
20
.BI "free_callback(" callback ");"
23
.BI "is_callback(" callback ")"
24
.BI "callback_address(" callback ")"
25
.BI "callback_data(" callback ")"
29
These functions implement
31
with variable arguments as first-class C functions.
34
.I first-class C functions
35
means that they fit into a function pointer and can be called exactly
36
like any other C function. Moreover, they can be called with variable
37
arguments and can return variable return values.
39
.IB callback " = alloc_callback(" "&function" ", " data ")"
40
allocates a callback. When
42
gets called, it arranges to call
46
as first argument and, as second argument, the entire sequence of arguments
50
Function calling conventions differ considerably on different machines,
51
therefore the arguments are accessed and the result value is stored
52
through the same macros as used by the
56
The callbacks are functions with indefinite extent:
58
is only deallocated when
59
.BI free_callback( callback )
62
.BI "is_callback(" callback ")"
63
checks whether the C function
65
was produced by a call to
67
If this returns true, the arguments given to
72
.BI "callback_address(" callback ")"
76
.BI "callback_data(" callback ")"
85
the following macros can be used to walk through the argument list and
86
specify a return value:
89
.BI "va_start_" type "(" alist "[, " return_type "]);"
90
starts the walk through the argument list and specifies the return type.
92
.IB arg " = va_arg_" type "(" alist "[, " arg_type "]);"
93
fetches the next argument from the argument list.
95
.BI "va_return_" type "(" alist "[[, " return_type "], " return_value "]);"
96
ends the walk through the argument list and specifies the return value.
106
.BR void ", " int ", " uint ", " long ", " ulong ", " longlong ", " ulonglong ", " double ", " struct ", " ptr
107
or (for ANSI C calling conventions only)
108
.BR char ", " schar ", " uchar ", " short ", " ushort ", " float ,
109
depending on the class of
132
.BR int ", " uint ", " long ", " ulong ", " longlong ", " ulonglong ", " double ", " struct ", " ptr
133
or (for ANSI C calling conventions only)
134
.BR char ", " schar ", " uchar ", " short ", " ushort ", " float ,
135
depending on the class of
139
.BI "va_start_struct(" alist ", " return_type ", " splittable );
142
flag specifies whether the struct
144
can be returned in registers such that every struct field fits entirely in
145
a single register. This needs to be specified for structs of size
146
2*sizeof(long). For structs of size <= sizeof(long),
148
is ignored and assumed to be 1. For structs of size > 2*sizeof(long),
150
is ignored and assumed to be 0. There are some handy macros for this:
152
.BI "va_word_splittable_1 (" type1 )
153
.BI "va_word_splittable_2 (" type1 ", " type2 )
154
.BI "va_word_splittable_3 (" type1 ", " type2 ", " type3 )
155
.BI "va_word_splittable_4 (" type1 ", " type2 ", " type3 ", " type4 )
157
For a struct with three slots
159
.BI "struct { " "type1 id1" "; " "type2 id2" "; " "type3 id3" "; }"
164
.BI "va_word_splittable_3 (" type1 ", " type2 ", " type3 )
169
Functions which want to emulate Kernighan & Ritchie style functions (i.e.,
170
in ANSI C, functions without a typed argument list) cannot use the
173
.BR char ", " schar ", " uchar ", " short ", " ushort ", " float .
174
As prescribed by the default K&R C expression promotions, they have
178
.BR char ", " schar ", " uchar ", " short ", " ushort
185
.BR va_start_longlong(\|) ,
186
.BR va_start_ulonglong(\|) ,
187
.BR va_return_longlong(\|) ,
188
.BR va_return_ulonglong(\|) ,
189
.B va_arg_longlong(\|)
191
.B va_arg_ulonglong(\|)
192
work only if the C compiler has a working
196
The struct types used in
197
.B va_start_struct(\|)
200
must only contain (signed or unsigned) int, long, long long or pointer fields.
201
Struct types containing (signed or unsigned) char, short, float, double or
202
other structs are not supported.
210
The current implementations have been tested on a selection of common
211
cases but there are probably still many bugs.
213
There are typically built-in limits on the size of the argument-list,
214
which may also include the size of any structure arguments.
216
The decision whether a struct is to be returned in registers or in memory
217
considers only the struct's size and alignment. This is inaccurate: for
218
example, gcc on m68k-next returns
219
.B "struct { char a,b,c; }"
221
.B "struct { char a[3]; }"
222
in memory, although both types have the same size and the same alignment.
225
cannot be included when
233
The argument list can only be walked once.
237
All information is passed in CPU registers and the stack. The
239
package is therefore multithread-safe.
245
consists in first porting the
249
packages, then choosing a CPU register for passing the closure from
253
This register is normally the register designated by STATIC_CHAIN_REGNUM
254
in the gcc source, file
255
.RI gcc-2.7.2/config/ cpu / cpu .h.
259
Bruno Haible <bruno@clisp.org>
263
Many ideas were cribbed from the gcc source.
added
removed
callback/callback.3
