.TH TRAMPOLINE 3 "22 October 1997"
.SH NAME
trampoline \- closures as first-class C functions
.SH SYNOPSIS
.B #include <trampoline_r.h>
.LP
.B function = alloc_trampoline_r(address, data0, data1);
.LP
.B free_trampoline_r(function);
.LP
.nf
.B is_trampoline_r(function)
.B trampoline_r_address(function)
.B trampoline_r_data0(function)
.B trampoline_r_data1(function)
.fi
.SH DESCRIPTION
.LP
These functions implement
.I 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
.I first-class C functions
means that they fit into a function
pointer and can be called exactly like any other C function.
.IB function " = alloc_trampoline_r(" address ", " data0 ", " data1 ")"
allocates a closure. When
.I function
gets called, it stores in a special "lexical chain register" a pointer to a
storage area containing
.I data0
in its first word and
.I data1
in its second word and calls the C function at
.IR address .
The function at
.I address
is responsible for fetching
.I data0
and
.I 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
.BR gcc "'s"
local functions, except that the GNU C local functions have dynamic extent
(i.e. are deallocated when the creating function returns), while
.I trampoline
provides functions with indefinite extent:
.I function
is only deallocated when
.BI free_trampoline_r( function )
is called.

.BI "is_trampoline_r(" function ")"
checks whether the C function
.I function
was produced by a call to
.IR alloc_trampoline_r .
If this returns true, the arguments given to
.I alloc_trampoline_r
can be retrieved:
.RS 4
.LP
.BI "trampoline_r_address(" function ")"
returns
.IR address ,
.LP
.BI "trampoline_r_data0(" function ")"
returns
.IR data0 ,
.LP
.BI "trampoline_r_data1(" function ")"
returns
.IR data1 .
.RE

.SH SEE ALSO
.BR trampoline (3),
.BR gcc (1),
.BR varargs (3)

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

.SH AUTHOR

Bruno Haible <bruno@clisp.org>

.SH ACKNOWLEDGEMENTS

Many ideas were cribbed from the gcc source.