.\" 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>.
.\"
.TH TRAMPOLINE 3 "1 January 2017"
.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 stdarg (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.