# TRAMPOLINE_R manual page

- Name
- Synopsis
- Description
- See also
- Porting
- Author
- Acknowledgements

## Name

trampoline_r - 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.

Last modified: 1 January 2017.