trampoline_r

TRAMPOLINE(3)               Library Functions Manual               TRAMPOLINE(3)



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), stdarg(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.




                                 1 January 2017                    TRAMPOLINE(3)