callback

CALLBACK(3)                 Library Functions Manual                 CALLBACK(3)



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

SYNOPSIS
       #include <callback.h>

       void function (data, alist)
         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
       These functions implement closures with variable arguments as first-class
       C functions.

       Closures as first-class C functions means that they fit into a function
       pointer and can be called exactly like any other C function. Moreover,
       they can be called with variable arguments and can return variable return
       values.

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

       Function calling conventions differ considerably on different machines,
       therefore the arguments are accessed and the result value is stored
       through the same macros as used by the vacall package, see below.

       The callbacks are functions with indefinite extent: callback is only
       deallocated when free_callback(callback) is called.

       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
       Within function, the following macros can be used 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.

       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. 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.

       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.

       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.


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.

       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.

       <callback.h> cannot be included when <varargs.h> or <stdarg.h> is
       included.  (Name clash for va_alist.)

       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.


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.




                                 14 January 2001                     CALLBACK(3)