File ffcall/trampoline/trampoline.man artifact 8a812f0b7c part of check-in 8723100e73





TRAMPOLINE(3)                                       TRAMPOLINE(3)


NNAAMMEE
       trampoline - closures as first-class C functions

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ttrraammppoolliinnee..hh>>

       ffuunnccttiioonn == aalllloocc__ttrraammppoolliinnee((aaddddrreessss,, vvaarriiaabbllee,, ddaattaa));;

       ffrreeee__ttrraammppoolliinnee((ffuunnccttiioonn));;

       iiss__ttrraammppoolliinnee((ffuunnccttiioonn))
       ttrraammppoolliinnee__aaddddrreessss((ffuunnccttiioonn))
       ttrraammppoolliinnee__vvaarriiaabbllee((ffuunnccttiioonn))
       ttrraammppoolliinnee__ddaattaa((ffuunnccttiioonn))

DDEESSCCRRIIPPTTIIOONN
       These  functions implement _c_l_o_s_u_r_e_s as first-class C func-
       tions.  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 _f_i_r_s_t_-_c_l_a_s_s _C _f_u_n_c_t_i_o_n_s means  that  they  fit
       into a function pointer and can be called exactly like any
       other C function.   _f_u_n_c_t_i_o_n  ==  aalllloocc__ttrraammppoolliinnee((_a_d_d_r_e_s_s,,
       _v_a_r_i_a_b_l_e,,  _d_a_t_a))  allocates  a closure. When _f_u_n_c_t_i_o_n gets
       called, it stores _d_a_t_a in the variable _v_a_r_i_a_b_l_e and  calls
       the  C  function  at  _a_d_d_r_e_s_s.  The function at _a_d_d_r_e_s_s is
       responsible for fetching _d_a_t_a out of _v_a_r_i_a_b_l_e immediately,
       before execution of any other function call.

       This  is  much like ggcccc's local functions, except that the
       GNU C local functions have dynamic extent (i.e. are  deal-
       located when the creating function returns), while _t_r_a_m_p_o_-
       _l_i_n_e provides functions with indefinite  extent:  _f_u_n_c_t_i_o_n
       is  only  deallocated  when  ffrreeee__ttrraammppoolliinnee((_f_u_n_c_t_i_o_n))  is
       called.

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

           ttrraammppoolliinnee__aaddddrreessss((_f_u_n_c_t_i_o_n)) returns _a_d_d_r_e_s_s,

           ttrraammppoolliinnee__vvaarriiaabbllee((_f_u_n_c_t_i_o_n)) returns _v_a_r_i_a_b_l_e,

           ttrraammppoolliinnee__ddaattaa((_f_u_n_c_t_i_o_n)) returns _d_a_t_a.


SSEEEE AALLSSOO
       ggcccc(1), vvaarraarrggss(3), ccaallllbbaacckk(3)






                         25 October 1997                        1





TRAMPOLINE(3)                                       TRAMPOLINE(3)


BBUUGGSS
       Passing  the  data  through a global variable is not reen-
       trant. Don't call trampoline functions from within  signal
       handlers. This is fixed in the ccaallllbbaacckk(3) package.


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


AAUUTTHHOORR
       Bruno Haible <bruno@clisp.org>


AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS
       Many ideas were cribbed from the gcc source.








































                         25 October 1997                        2