.\" 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 CALLBACK 3 "1 January 2017"
.SH NAME
callback \- closures with variable arguments as first-class C functions
.SH SYNOPSIS
.B #include <callback.h>
.LP
.nf
.BI "void " function " (void* " data ", va_alist " alist ")"
.BI "{"
.BI "  va_start_" type "(" alist "[, " return_type "]);"
.BI "  " arg " = va_arg_" type "(" alist "[, " arg_type "]);"
.BI "  va_return_" type "(" alist "[[, " return_type "], " return_value "]);"
.BI "}"
.fi
.LP
.IB callback " = alloc_callback(" "&function" ", " data ");"
.LP
.BI "free_callback(" callback ");"
.LP
.nf
.BI "is_callback(" callback ")"
.BI "callback_address(" callback ")"
.BI "callback_data(" callback ")"
.fi
.SH DESCRIPTION
.LP
These functions implement
.I closures
with variable arguments as first-class C functions.

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. Moreover, they can be called with variable
arguments and can return variable return values.

.IB callback " = alloc_callback(" "&function" ", " data ")"
allocates a callback. When
.I callback
gets called, it arranges to call
.IR function ","
passing
.I data
as first argument and, as second argument, the entire sequence of arguments
passed to
.IR callback .

Function calling conventions differ considerably on different machines,
therefore the arguments are accessed and the result value is stored
through the same macros as used by the
.I vacall
package, see below.

The callbacks are functions with indefinite extent:
.I callback
is only deallocated when
.BI free_callback( callback )
is called.

.BI "is_callback(" callback ")"
checks whether the C function
.I callback
was produced by a call to
.IR alloc_callback .
If this returns true, the arguments given to
.I alloc_callback
can be retrieved:
.RS 4
.LP
.BI "callback_address(" callback ")"
returns
.IR "&function" ,
.LP
.BI "callback_data(" callback ")"
returns
.IR data .
.RE

.SH VACALL MACROS

Within
.IR function ,
the following macros can be used to walk through the argument list and
specify a return value:
.RS 0
.TP
.BI "va_start_" type "(" alist "[, " return_type "]);"
starts the walk through the argument list and specifies the return type.
.TP
.IB arg " = va_arg_" type "(" alist "[, " arg_type "]);"
fetches the next argument from the argument list.
.TP
.BI "va_return_" type "(" alist "[[, " return_type "], " return_value "]);"
ends the walk through the argument list and specifies the return value.
.RE

The
.I type
in
.BI va_start_ type
and
.BI va_return_ type
shall be one of
.BR void ", " int ", " uint ", " long ", " ulong ", " longlong ", " ulonglong ", " double ", " struct ", " ptr
or (for ANSI C calling conventions only)
.BR char ", " schar ", " uchar ", " short ", " ushort ", " float ,
depending on the class of
.IR return_type .

The
.I type
specifiers in
.BI va_start_ type
and
.BI va_return_ type
must be the same.
The
.I return_type
specifiers passed to
.BI va_start_ type
and
.BI va_return_ type
must be the same.

The
.I type
in
.BI va_arg_ type
shall be one of
.BR int ", " uint ", " long ", " ulong ", " longlong ", " ulonglong ", " double ", " struct ", " ptr
or (for ANSI C calling conventions only)
.BR char ", " schar ", " uchar ", " short ", " ushort ", " float ,
depending on the class of
.IR arg_type .

In
.BI "va_start_struct(" alist ", " return_type ", " splittable );
the
.I splittable
flag specifies whether the struct
.I return_type
can be returned in registers such that every struct field fits entirely in
a single register. This needs to be specified for structs of size
2*sizeof(long). For structs of size <= sizeof(long),
.I splittable
is ignored and assumed to be 1. For structs of size > 2*sizeof(long),
.I splittable
is ignored and assumed to be 0. There are some handy macros for this:
.nf
.BI "va_word_splittable_1 (" type1 )
.BI "va_word_splittable_2 (" type1 ", " type2 )
.BI "va_word_splittable_3 (" type1 ", " type2 ", " type3 )
.BI "va_word_splittable_4 (" type1 ", " type2 ", " type3 ", " type4 )
.fi
For a struct with three slots
.nf
.BI "struct { " "type1 id1" "; " "type2 id2" "; " "type3 id3" "; }"
.fi
you can specify
.I splittable
as
.BI "va_word_splittable_3 (" type1 ", " type2 ", " type3 )
.RB .

.SH NOTES

Functions which want to emulate Kernighan & Ritchie style functions (i.e.,
in ANSI C, functions without a typed argument list) cannot use the
.I type
values
.BR char ", " schar ", " uchar ", " short ", " ushort ", " float .
As prescribed by the default K&R C expression promotions, they have
to use
.B int
instead of
.BR char ", " schar ", " uchar ", " short ", " ushort
and
.B double
instead of
.BR float .

The macros
.BR va_start_longlong(\|) ,
.BR va_start_ulonglong(\|) ,
.BR va_return_longlong(\|) ,
.BR va_return_ulonglong(\|) ,
.B va_arg_longlong(\|)
and
.B va_arg_ulonglong(\|)
work only if the C compiler has a working
.B long long
64-bit integer type.

The struct types used in
.B va_start_struct(\|)
and
.B va_struct(\|)
must only contain (signed or unsigned) int, long, long long or pointer fields.
Struct types containing (signed or unsigned) char, short, float, double or
other structs are not supported.

.SH SEE ALSO
.BR vacall (3),
.BR trampoline (3).

.SH BUGS

The current implementations have been tested on a selection of common
cases but there are probably still many bugs.

There are typically built-in limits on the size of the argument-list,
which may also include the size of any structure arguments.

The decision whether a struct is to be returned in registers or in memory
considers only the struct's size and alignment. This is inaccurate: for
example, gcc on m68k-next returns
.B "struct { char a,b,c; }"
in registers and
.B "struct { char a[3]; }"
in memory, although both types have the same size and the same alignment.

The argument list can only be walked once.

.SH NON-BUGS

All information is passed in CPU registers and the stack. The
.B callback
package is therefore multithread-safe.

.SH PORTING

Porting
.B callback
consists in first porting the
.B vacall
and
.B trampoline
packages, then choosing a CPU register for passing the closure from
.B trampoline
to
.BR vacall .
This register is normally the register designated by STATIC_CHAIN_REGNUM
in the gcc source, file
.RI gcc-2.7.2/config/ cpu / cpu .h.

.SH AUTHOR

Bruno Haible <bruno@clisp.org>

.SH ACKNOWLEDGEMENTS

Many ideas were cribbed from the gcc source.