<HTML> <HEAD> <!-- Copyright (C) 1995-2017 Bruno Haible This manual is free documentation. It is dually licensed under the GNU FDL and the GNU GPL. This means that you can redistribute this manual under either of these two licenses, at your choice. This manual is covered by the GNU FDL. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (FDL), either version 1.2 of the License, or (at your option) any later version published by the Free Software Foundation (FSF); with no Invariant Sections, with no Front-Cover Text, and with no Back-Cover Texts. A copy of the license is at <https://www.gnu.org/licenses/old-licenses/fdl-1.2>. This manual is covered by the GNU GPL. You can redistribute it and/or modify it under the terms of the GNU General Public License (GPL), either version 2 of the License, or (at your option) any later version published by the Free Software Foundation (FSF). A copy of the license is at <https://www.gnu.org/licenses/old-licenses/gpl-2.0>. --> <TITLE> TRAMPOLINE manual page </TITLE> </HEAD> <BODY> <H1>TRAMPOLINE manual page</H1> <UL> <LI> <A HREF="#Name">Name</A> <LI> <A HREF="#Synopsis">Synopsis</A> <LI> <A HREF="#Description">Description</A> <LI> <A HREF="#See also">See also</A> <LI> <A HREF="#Bugs">Bugs</A> <LI> <A HREF="#Porting">Porting</A> <LI> <A HREF="#Author">Author</A> <LI> <A HREF="#Acknowledgements">Acknowledgements</A> </UL> <P> <HR> <A NAME="Name"> <H2>Name</H2> </A> trampoline - closures as first-class C functions <A NAME="Synopsis"> <H2>Synopsis</H2> </A> <PRE> <CODE>#include <trampoline.h></CODE> <CODE><VAR>function</VAR> = alloc_trampoline(<VAR>address</VAR>, <VAR>variable</VAR>, <VAR>data</VAR>);</CODE> <CODE>free_trampoline(<VAR>function</VAR>);</CODE> <CODE>is_trampoline(<VAR>function</VAR>)</CODE> <CODE>trampoline_address(<VAR>function</VAR>)</CODE> <CODE>trampoline_variable(<VAR>function</VAR>)</CODE> <CODE>trampoline_data(<VAR>function</VAR>)</CODE> </PRE> <A NAME="Description"> <H2>Description</H2> </A> These functions implement <EM>closures</EM> 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. <P> Closures as <EM>first-class C functions</EM> means that they fit into a function pointer and can be called exactly like any other C function. <CODE><VAR>function</VAR> = alloc_trampoline(<VAR>address</VAR>, <VAR>variable</VAR>, <VAR>data</VAR>)</CODE> allocates a closure. When <VAR>function</VAR> gets called, it stores <VAR>data</VAR> in the variable <VAR>variable</VAR> and calls the C function at <VAR>address</VAR>. The function at <VAR>address</VAR> is responsible for fetching <VAR>data</VAR> out of <VAR>variable</VAR> immediately, before execution of any other function call. <P> 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 <EM>trampoline</EM> provides functions with indefinite extent: <CODE><VAR>function</VAR></CODE> is only deallocated when <CODE>free_trampoline(<VAR>function</VAR>)</CODE> is called. <P> <CODE>is_trampoline(<VAR>function</VAR>)</CODE> checks whether the C function <CODE><VAR>function</VAR></CODE> was produced by a call to <CODE>alloc_trampoline</CODE>. If this returns true, the arguments given to <CODE>alloc_trampoline</CODE> can be retrieved: <UL> <LI> <CODE>trampoline_address(<VAR>function</VAR>)</CODE> returns <VAR>address</VAR>, <LI> <CODE>trampoline_variable(<VAR>function</VAR>)</CODE> returns <VAR>variable</VAR>, <LI> <CODE>trampoline_data(<VAR>function</VAR>)</CODE> returns <VAR>data</VAR>. </UL> <A NAME="See also"> <H2>See also</H2> </A> <A HREF="gcc(1)"><CODE><B>gcc</B></CODE></A>(1), <A HREF="stdarg(3)"><CODE><B>stdarg</B></CODE></A>(3), <A HREF="callback(3)"><CODE><B>callback</B></CODE></A>(3) <A NAME="Bugs"> <H2>Bugs</H2> </A> Passing the data through a global variable is not reentrant. Don't call trampoline functions from within signal handlers. This is fixed in the <A HREF="callback(3)"><CODE><B>callback</B></CODE></A>(3) package. <A NAME="Porting"> <H2>Porting</H2> </A> The way gcc builds local functions is described in the gcc source, file <SAMP>gcc-2.6.3/config/<VAR>cpu</VAR>/<VAR>cpu</VAR>.h</SAMP>. <A NAME="Author"> <H2>Author</H2> </A> Bruno Haible <bruno@clisp.org> <A NAME="Acknowledgements"> <H2>Acknowledgements</H2> </A> Many ideas were cribbed from the gcc source. <P> <HR> <ADDRESS>TRAMPOLINE manual page<BR> Bruno Haible <bruno@clisp.org> </ADDRESS> <P> Last modified: 1 January 2017. </BODY> </HTML>