NAME

       trampoline - closures as first-class C functions

SYNOPSIS

       #include <trampoline_r.h>

       function = alloc_trampoline_r(address, data0, data1);

       free_trampoline_r(function);

       is_trampoline_r(function)
       trampoline_r_address(function)
       trampoline_r_data0(function)
       trampoline_r_data1(function)

DESCRIPTION

       These  functions  implement  closures as first-class C functions.  A closure consists of a
       regular C function and a piece of data which gets  passed  to  the  C  function  when  the
       closure is called.

       Closures as first-class C functions means that they fit into a function pointer and can be
       called exactly like any other C function.  function =  alloc_trampoline_r(address,  data0,
       data1)  allocates  a  closure.  When function gets called, it stores in a special "lexical
       chain register" a pointer to a storage area containing data0 in its first word  and  data1
       in  its  second  word  and  calls  the  C function at address.  The function at address is
       responsible for fetching data0 and data1 off the pointer. Note  that  the  "lexical  chain
       register" is a call-used register, i.e. is clobbered by function calls.

       This  is  much  like  gcc's  local  functions,  except that the GNU C local functions have
       dynamic extent (i.e. are deallocated when the creating function returns), while trampoline
       provides   functions   with   indefinite   extent:   function  is  only  deallocated  when
       free_trampoline_r(function) is called.

       is_trampoline_r(function) checks whether the C function function was produced by a call to
       alloc_trampoline_r.   If  this returns true, the arguments given to alloc_trampoline_r can
       be retrieved:

           trampoline_r_address(function) returns address,

           trampoline_r_data0(function) returns data0,

           trampoline_r_data1(function) returns data1.

SEE ALSO

       trampoline(3), gcc(1), varargs(3)

PORTING

       The  way  gcc  builds  local  functions   is   described   in   the   gcc   source,   file
       gcc-2.6.3/config/cpu/cpu.h.

AUTHOR

       Bruno Haible <bruno@clisp.org>

ACKNOWLEDGEMENTS

       Many ideas were cribbed from the gcc source.

                                         22 October 1997                            TRAMPOLINE(3)