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)