← Back to branch summary

~ubuntu-branches/debian/squeeze/ffcall/squeeze

« back to all changes in this revision

Viewing changes to ffcall/callback/callback.html

  • Committer: Bazaar Package Importer
  • Author(s): Christoph Egger
  • Date: 2010-06-26 15:29:30 UTC
  • mfrom: (5.1.1 experimental)
  • Revision ID: james.westby@ubuntu.com-20100626152930-c09y01gk3szcnykn
Tags: 1.10+cvs20100619-2
Ship to unstable

Show diffs side-by-side

added added

removed removed

Lines of Context:
ffcall/callback/callback.html
1
 
<HEAD>
2
 
<TITLE> CALLBACK manual page </TITLE>
3
 
</HEAD>
4
 
<BODY>
5
 
<H1>CALLBACK manual page</H1>
6
 
 
7
 
<UL>
8
 
<LI> <A HREF="#Name">Name</A>
9
 
<LI> <A HREF="#Synopsis">Synopsis</A>
10
 
<LI> <A HREF="#Description">Description</A>
11
 
<LI> <A HREF="#VACALL macros">VACALL macros</A>
12
 
<LI> <A HREF="#Notes">Notes</A>
13
 
<LI> <A HREF="#See also">See also</A>
14
 
<LI> <A HREF="#Bugs">Bugs</A>
15
 
<LI> <A HREF="#Non-Bugs">Non-Bugs</A>
16
 
<LI> <A HREF="#Porting">Porting</A>
17
 
<LI> <A HREF="#Author">Author</A>
18
 
<LI> <A HREF="#Acknowledgements">Acknowledgements</A>
19
 
</UL>
20
 
<P>
21
 
 
22
 
<HR>
23
 
 
24
 
<A NAME="Name">
25
 
<H2>Name</H2>
26
 
</A>
27
 
 
28
 
callback - closures with variable arguments as first-class
29
 
C functions
30
 
 
31
 
<A NAME="Synopsis">
32
 
<H2>Synopsis</H2>
33
 
</A>
34
 
 
35
 
<PRE>
36
 
<CODE>#include &lt;callback.h&gt;</CODE>
37
 
</PRE>
38
 
<P>
39
 
<PRE>
40
 
<CODE>void <VAR>function</VAR> (<VAR>data</VAR>, <VAR>alist</VAR>)</CODE>
41
 
<CODE>  void* <VAR>data</VAR>;</CODE>
42
 
<CODE>  va_alist <VAR>alist</VAR>;</CODE>
43
 
<CODE>{</CODE>
44
 
<CODE>  va_start_<VAR>type</VAR>(<VAR>alist</VAR>[, <VAR>return_type</VAR>]);</CODE>
45
 
<CODE>  arg = va_arg_<VAR>type</VAR>(<VAR>alist</VAR>[, <VAR>arg_type</VAR>]);</CODE>
46
 
<CODE>  va_return_<VAR>type</VAR>(<VAR>alist</VAR>[[, <VAR>return_type</VAR>], <VAR>return_value</VAR>]);</CODE>
47
 
<CODE>}</CODE>
48
 
</PRE>
49
 
<P>
50
 
<PRE>
51
 
<CODE><VAR>callback</VAR> = alloc_callback(<VAR>&function</VAR>, <VAR>data</VAR>);</CODE>
52
 
</PRE>
53
 
<P>
54
 
<PRE>
55
 
<CODE>free_callback(<VAR>callback</VAR>);</CODE>
56
 
</PRE>
57
 
<P>
58
 
<PRE>
59
 
<CODE>is_callback(<VAR>callback</VAR>)</CODE>
60
 
<CODE>callback_address(<VAR>callback</VAR>)</CODE>
61
 
<CODE>callback_data(<VAR>callback</VAR>)</CODE>
62
 
</PRE>
63
 
 
64
 
<A NAME="Description">
65
 
<H2>Description</H2>
66
 
</A>
67
 
 
68
 
These functions implement <EM>closures</EM> with variable arguments
69
 
as first-class C functions.
70
 
<P>
71
 
Closures  as  <EM>first-class  C functions</EM> means that they fit
72
 
into a function pointer and can be called exactly like any
73
 
other  C function. Moreover, they can be called with variable
74
 
arguments and can return variable return values.
75
 
<P>
76
 
<CODE><VAR>callback</VAR> = alloc_callback(<VAR>&function</VAR>, <VAR>data</VAR>)</CODE>
77
 
allocates  a
78
 
callback.  When  <VAR>callback</VAR> gets called, it arranges to call
79
 
<VAR>function</VAR>, passing <VAR>data</VAR> as first argument  and,  as  second
80
 
argument, the entire sequence of arguments passed to <VAR>callback</VAR>.
81
 
<P>
82
 
Function calling conventions differ considerably  on  different
83
 
machines, therefore the arguments are accessed and
84
 
the result value is stored through the same macros as used
85
 
by the <EM>vacall</EM> package, see below.
86
 
<P>
87
 
The  callbacks are functions with indefinite extent: <CODE><VAR>callback</VAR></CODE>
88
 
is only deallocated when  <CODE>free_callback(<VAR>callback</VAR>)</CODE>  is
89
 
called.
90
 
<P>
91
 
<CODE>is_callback(<VAR>callback</VAR>)</CODE>
92
 
checks whether the C function <CODE><VAR>callback</VAR></CODE>
93
 
was produced by a call to  <CODE>alloc_callback</CODE>.   If  this
94
 
returns true, the arguments given to <CODE>alloc_callback</CODE> can be
95
 
retrieved:
96
 
<UL>
97
 
<LI> <CODE>callback_address(<VAR>callback</VAR>)</CODE> returns <VAR>&function</VAR>,
98
 
<LI> <CODE>callback_data(<VAR>callback</VAR>)</CODE> returns <VAR>data</VAR>.
99
 
</UL>
100
 
 
101
 
<A NAME="VACALL macros">
102
 
<H2>VACALL macros</H2>
103
 
</A>
104
 
 
105
 
Within <VAR>function</VAR>, the following macros can be used to walk
106
 
through the argument list and specify a return value:
107
 
<P>
108
 
<PRE>
109
 
<CODE>va_start_<VAR>type</VAR>(<VAR>alist</VAR>[, <VAR>return_type</VAR>]);</CODE>
110
 
</PRE>
111
 
starts the walk through the argument list and specifies the return type.
112
 
<P>
113
 
<PRE>
114
 
<CODE>arg = va_arg_<VAR>type</VAR>(<VAR>alist</VAR>[, <VAR>arg_type</VAR>]);</CODE>
115
 
</PRE>
116
 
fetches the next argument from the argument list.
117
 
<P>
118
 
<PRE>
119
 
<CODE>va_return_<VAR>type</VAR>(<VAR>alist</VAR>[[, <VAR>return_type</VAR>], <VAR>return_value</VAR>]);</CODE>
120
 
</PRE>
121
 
ends  the walk through the argument list and specifies the return value.
122
 
<P>
123
 
The <VAR>type</VAR> in <CODE>va_start_<VAR>type</VAR></CODE>
124
 
 and <CODE>va_return_<VAR>type</VAR></CODE> shall be  one
125
 
of <CODE>void</CODE>,  <CODE>int</CODE>,  <CODE>uint</CODE>, <CODE>long</CODE>,
126
 
<CODE>ulong</CODE>, <CODE>longlong</CODE>, <CODE>ulonglong</CODE>,
127
 
<CODE>double</CODE>, <CODE>struct</CODE>, <CODE>ptr</CODE>
128
 
or
129
 
(for ANSI C calling conventions only)
130
 
<CODE>char</CODE>, <CODE>schar</CODE>,  <CODE>uchar</CODE>,
131
 
<CODE>short</CODE>,   <CODE>ushort</CODE>,   <CODE>float</CODE>,
132
 
depending   on  the  class  of <VAR>return_type</VAR>.
133
 
<P>
134
 
The <VAR>type</VAR> specifiers in
135
 
<CODE>va_start_<VAR>type</VAR></CODE> and <CODE>va_return_<VAR>type</VAR></CODE>
136
 
 must be the same.
137
 
The <VAR>return_type</VAR> specifiers   passed    to
138
 
<CODE>va_start_<VAR>type</VAR></CODE> and <CODE>va_return_<VAR>type</VAR></CODE>
139
 
 must be the same.
140
 
<P>
141
 
The <VAR>type</VAR> in <CODE>va_arg_<VAR>type</VAR></CODE>
142
 
shall be one of <CODE>int</CODE>,  <CODE>uint</CODE>, <CODE>long</CODE>,
143
 
<CODE>ulong</CODE>, <CODE>longlong</CODE>, <CODE>ulonglong</CODE>,
144
 
<CODE>double</CODE>, <CODE>struct</CODE>, <CODE>ptr</CODE>
145
 
or (for ANSI C calling  conventions  only)
146
 
<CODE>char</CODE>, <CODE>schar</CODE>,  <CODE>uchar</CODE>,
147
 
<CODE>short</CODE>,   <CODE>ushort</CODE>,   <CODE>float</CODE>,
148
 
depending   on  the  class  of <VAR>arg_type</VAR>.
149
 
<P>
150
 
In <CODE>va_start_struct(<VAR>alist</VAR>, <VAR>return_type</VAR>, <VAR>splittable</VAR>);</CODE> the
151
 
<VAR>splittable</VAR> flag specifies whether the struct <VAR>return_type</VAR> can
152
 
be returned in registers such that every struct field fits
153
 
entirely  in a single register. This needs to be specified
154
 
for structs of size <SAMP>2*sizeof(long)</SAMP>. For structs of size
155
 
&lt;= <SAMP>sizeof(long)</SAMP>,  splittable  is ignored and assumed to be 1.
156
 
For  structs  of  size  &gt; <SAMP>2*sizeof(long)</SAMP>,  splittable  is
157
 
ignored  and  assumed to be 0. There are some handy macros
158
 
for this:
159
 
<PRE>
160
 
<CODE>va_word_splittable_1 (<VAR>type1</VAR>)</CODE>
161
 
<CODE>va_word_splittable_2 (<VAR>type1</VAR>, <VAR>type2</VAR>)</CODE>
162
 
<CODE>va_word_splittable_3 (<VAR>type1</VAR>, <VAR>type2</VAR>, <VAR>type3</VAR>)</CODE>
163
 
<CODE>va_word_splittable_4 (<VAR>type1</VAR>, <VAR>type2</VAR>, <VAR>type3</VAR>, <VAR>type4</VAR>)</CODE>
164
 
</PRE>
165
 
For a struct with three slots
166
 
<PRE>
167
 
<CODE>struct { <VAR>type1 id1</VAR>; <VAR>type2 id2</VAR>; <VAR>type3 id3</VAR>; }</CODE>
168
 
</PRE>
169
 
you can specify <VAR>splittable</VAR> as
170
 
<CODE>va_word_splittable_3 (<VAR>type1</VAR>, <VAR>type2</VAR>, <VAR>type3</VAR>)</CODE>.
171
 
 
172
 
<A NAME="Notes">
173
 
<H2>Notes</H2>
174
 
</A>
175
 
 
176
 
<OL>
177
 
<LI> Functions which want to emulate Kernighan &amp; Ritchie  style
178
 
functions  (i.e.,  in  ANSI  C,  functions without a typed
179
 
argument list) cannot use the <VAR>type</VAR>  values
180
 
<CODE>char</CODE>, <CODE>schar</CODE>,  <CODE>uchar</CODE>,
181
 
<CODE>short</CODE>,   <CODE>ushort</CODE>,   <CODE>float</CODE>.
182
 
As prescribed by the default
183
 
K&amp;R C expression promotions, they have to use <CODE>int</CODE>  instead
184
 
of <CODE>char</CODE>, <CODE>schar</CODE>,  <CODE>uchar</CODE>,
185
 
<CODE>short</CODE>,   <CODE>ushort</CODE> and <CODE>double</CODE> instead of
186
 
<CODE>float</CODE>.
187
 
<P>
188
 
<LI> The macros <CODE>va_start_longlong()</CODE>,
189
 
<CODE>va_start_ulonglong()</CODE>, <CODE>va_return_longlong()</CODE>,
190
 
<CODE>va_return_ulonglong()</CODE>, <CODE>va_arg_longlong()</CODE> and
191
 
<CODE>va_arg_ulonglong()</CODE> work only if the C compiler has a working
192
 
<CODE>long long</CODE> 64-bit integer type.
193
 
<P>
194
 
<LI> The struct types used in <CODE>va_start_struct()</CODE> and
195
 
<CODE>va_struct()</CODE> must only contain (signed or unsigned) int,
196
 
long, long long or pointer fields. Struct types containing
197
 
(signed or unsigned) char, short, float, double or other
198
 
structs are not supported.
199
 
<P>
200
 
</OL>
201
 
 
202
 
<A NAME="See also">
203
 
<H2>See also</H2>
204
 
</A>
205
 
 
206
 
<A HREF="vacall(3)"><CODE><B>vacall</B></CODE></A>(3), <A HREF="trampoline(3)"><CODE><B>trampoline</B></CODE></A>(3).
207
 
 
208
 
<A NAME="Bugs">
209
 
<H2>Bugs</H2>
210
 
</A>
211
 
 
212
 
The  current  implementations have been tested on a selection
213
 
of common cases but there  are  probably  still  many
214
 
bugs.
215
 
<P>
216
 
There  are  typically  built-in  limits on the size of the
217
 
argument-list, which may also  include  the  size  of  any
218
 
structure arguments.
219
 
<P>
220
 
The decision whether a struct is to be returned in registers or in memory
221
 
considers only the struct's size and alignment. This is inaccurate: for
222
 
example, gcc on m68k-next returns
223
 
<CODE>struct { char a,b,c; }</CODE>
224
 
in registers and
225
 
<CODE>struct { char a[3]; }</CODE>
226
 
in memory, although both types have the same size and the same alignment.
227
 
<P>
228
 
<CODE>&lt;callback.h&gt;</CODE> cannot be included  when <CODE>&lt;varargs.h&gt;</CODE>  or
229
 
<CODE>&lt;stdarg.h&gt;</CODE> is included.  (Name clash for <CODE>va_alist</CODE>.)
230
 
<P>
231
 
The argument list can only be walked once.
232
 
 
233
 
<A NAME="Non-Bugs">
234
 
<H2>Non-Bugs</H2>
235
 
</A>
236
 
 
237
 
All  information is passed in CPU registers and the stack.
238
 
The <CODE><B>callback</B></CODE> package is therefore multithread-safe.
239
 
 
240
 
<A NAME="Porting">
241
 
<H2>Porting</H2>
242
 
</A>
243
 
 
244
 
Porting <CODE><B>callback</B></CODE> consists in first porting the <CODE><B>vacall</B></CODE>  and
245
 
<CODE><B>trampoline</B></CODE>  packages,  then  choosing  a  CPU register for
246
 
passing the closure from <EM>trampoline</EM> to <EM>vacall</EM>.  This
247
 
register    is    normally   the   register   designated   by
248
 
<CODE>STATIC_CHAIN_REGNUM</CODE> in the gcc source, file
249
 
<SAMP>gcc-2.7.2/config/<VAR>cpu</VAR>/<VAR>cpu</VAR>.h</SAMP>.
250
 
 
251
 
<A NAME="Author">
252
 
<H2>Author</H2>
253
 
</A>
254
 
 
255
 
Bruno Haible &lt;bruno@clisp.org&gt;
256
 
 
257
 
<A NAME="Acknowledgements">
258
 
<H2>Acknowledgements</H2>
259
 
</A>
260
 
 
261
 
Many ideas were cribbed from the gcc source.
262
 
<P>
263
 
 
264
 
<HR>
265
 
 
266
 
<ADDRESS>CALLBACK manual page<BR>
267
 
Bruno Haible &lt;bruno@clisp.org&gt;
268
 
</ADDRESS>
269
 
<P>
270
 
Last modified: 14 January 2001.
271
 
 
272
 
</BODY>