callback man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

CALLBACK(3)							   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 argu‐
       ments 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 pro‐
       duced 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, long‐
       long, 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 pre‐
       scribed 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_long‐
       long(), 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 mem‐
       ory considers only the struct's size and alignment. This is inaccurate:
       for example, gcc on m68k-next returns struct { char a,b,c; } in	regis‐
       ters  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	desig‐
       nated  by  STATIC_CHAIN_REGNUM  in  the gcc source, file gcc-2.7.2/con‐
       fig/cpu/cpu.h.

AUTHOR
       Bruno Haible <bruno@clisp.org>

ACKNOWLEDGEMENTS
       Many ideas were cribbed from the gcc source.

				14 January 2001			   CALLBACK(3)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net