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)