Mercurial > pub > dyncall > dyncall
annotate doc/manual/manual_bindings.tex @ 504:f263eb7a206e
- call_suite: made output more consistent with dyncall sig style
author | Tassilo Philipp |
---|---|
date | Fri, 08 Apr 2022 20:33:14 +0200 |
parents | 17287342e273 |
children | 48eede2fa034 |
rev | line source |
---|---|
0 | 1 %////////////////////////////////////////////////////////////////////////////// |
2 % | |
3 % Copyright (c) 2007,2009 Daniel Adler <dadler@uni-goettingen.de>, | |
4 % Tassilo Philipp <tphilipp@potion-studios.com> | |
5 % | |
6 % Permission to use, copy, modify, and distribute this software for any | |
7 % purpose with or without fee is hereby granted, provided that the above | |
8 % copyright notice and this permission notice appear in all copies. | |
9 % | |
10 % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
11 % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
13 % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
17 % | |
18 %////////////////////////////////////////////////////////////////////////////// | |
19 | |
467 | 20 \clearpage |
0 | 21 \section{Bindings to programming languages} |
22 | |
23 Through binding of the \product{dyncall} library into a scripting environment, | |
24 the scripting language can gain system programming status to a certain degree.\\ | |
25 The \product{dyncall} library provides bindings to Erlang\cite{Erlang}, Java\cite{Java}, | |
26 Lua\cite{Lua}, Python\cite{Python}, R\cite{R}, Ruby\cite{Ruby}, Go\cite{Go} and the shell/command line.\\ | |
27 However, please note that some of these bindings are work-in-progress and not | |
28 automatically tested, meaning it might require some additional work to make them | |
29 work. | |
30 | |
31 \subsection{Common Architecture} | |
32 | |
33 The binding interfaces of the \product{dyncall} library to various scripting | |
34 languages share a common set of functionality to invoke a function call. | |
35 | |
36 \subsubsection{Dynamic loading of code} | |
37 | |
38 The helper library \emph{dynload} which accompanies the \product{dyncall} | |
39 library provides an abstract interface to operating-system specific mechanisms | |
40 for loading and accessing executable code out of, but not limited to, shared | |
41 libraries. | |
42 | |
43 \subsubsection{Functions} | |
44 | |
45 All bindings are based on a common interface convention providing a common set | |
46 of the following 4 functions (exact spelling depending on the binding's scripting | |
47 environment): | |
48 \begin{description} | |
49 \item [load] - load a module of compiled code | |
50 \item [free] - unload a module of compiled code | |
51 \item [find] - find function pointer by symbolic names | |
52 \item [call] - invoke a function call | |
53 \end{description} | |
54 | |
55 \pagebreak | |
56 | |
57 \subsubsection{Signatures} | |
58 | |
59 A signature is a character string that represents a function's arguments and | |
60 return value types. It is used in the scripting language bindings invoke | |
61 functions to perform automatic type-conversion of the languages' types to the | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
62 low-level C/C++ data types. |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
63 This is an essential part of mapping the more flexible and often abstract data |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
64 types provided in scripting languages to the strict machine-level data types |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
65 used by C-libraries. |
0 | 66 The high-level C interface functions \capi{dcCallF()}, \capi{dcVCallF()}, |
67 \capi{dcArgF()} and \capi{dcVArgF()} of the \product{dyncall} library also make | |
68 use of this signature string format.\\ | |
69 \\ | |
70 The format of a \product{dyncall} signature string is as depicted below: | |
71 | |
72 | |
73 \paragraph{\product{dyncall} signature string format} | |
74 | |
75 \begin{center} | |
76 \group{input parameter type signature character}* \sigchar{)} \group{return | |
77 type signature character} \\ | |
78 \end{center} | |
79 | |
80 The \group{input parameter type signature character} sequence left to the | |
81 \sigchar{)} is in left-to-right order of the corresponding C function | |
82 parameter type list.\\ | |
83 The special \group{return type signature character} \sigchar{v} specifies | |
84 that the function does not return a value and corresponds to \capi{void} | |
85 functions in C. | |
86 | |
87 \begin{table}[h] | |
88 \begin{center} | |
89 \begin{tabular*}{0.75\textwidth}{cl} | |
90 Signature character & C/C++ data type \\ | |
91 \hline | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
92 \sigchar{v} & void \\ |
0 | 93 \sigchar{B} & \_Bool, bool \\ |
94 \sigchar{c} & char \\ | |
95 \sigchar{C} & unsigned char \\ | |
96 \sigchar{s} & short \\ | |
97 \sigchar{S} & unsigned short \\ | |
98 \sigchar{i} & int \\ | |
99 \sigchar{I} & unsigned int \\ | |
100 \sigchar{j} & long \\ | |
101 \sigchar{J} & unsigned long \\ | |
102 \sigchar{l} & long long, int64\_t \\ | |
103 \sigchar{L} & unsigned long long, uint64\_t \\ | |
104 \sigchar{f} & float \\ | |
105 \sigchar{d} & double \\ | |
106 \sigchar{p} & void* \\ | |
107 \sigchar{Z} & const char* (pointing to C string) \\ | |
490 | 108 \sigchar{A} & aggregate (struct, union) by-value \\ |
0 | 109 \end{tabular*} |
110 \caption{Type signature encoding for function call data types} | |
111 \label{sigchar} | |
112 \end{center} | |
113 \end{table} | |
114 | |
115 Please note that using a \sigchar{(} at the beginning of a signature string is possible, | |
116 although not required. The character doesn't have any meaning and will simply be | |
117 ignored. However, using it prevents annoying syntax highlighting problems with some code | |
118 editors. | |
119 | |
120 \pagebreak | |
121 | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
122 Calling convention modes can be switched using the signature string, as well. A |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
123 '\_' in the signature string is followed by a character specifying what |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
124 calling convention to use, as this affects how arguments are passed. This makes |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
125 only sense if there are multiple co-existing calling conventions on a single platform. |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
126 Usually, this is done at the beginning of the string, except in special cases, like |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
127 specifying where the varargs part of a variadic function begins. |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
128 The following signature characters exist: |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
129 |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
130 \begin{table}[h] |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
131 \begin{center} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
132 \begin{tabular*}{0.75\textwidth}{cl} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
133 Signature character & Calling Convention \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
134 \hline |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
135 \sigchar{:} & platform's default calling convention \\ |
490 | 136 \sigchar{*} & platform's default C++/thiscall calling convention \\ |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
137 \sigchar{e} & vararg function \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
138 \sigchar{.} & vararg function's variadic/ellipsis part (...), to be specified before first vararg \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
139 \sigchar{c} & only on x86: cdecl \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
140 \sigchar{s} & only on x86: stdcall \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
141 \sigchar{F} & only on x86: fastcall (MS) \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
142 \sigchar{f} & only on x86: fastcall (GNU) \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
143 \sigchar{+} & only on x86: thiscall (MS) \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
144 \sigchar{\#}& only on x86: thiscall (GNU) \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
145 \sigchar{A} & only on ARM: ARM mode \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
146 \sigchar{a} & only on ARM: THUMB mode \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
147 \sigchar{\$}& syscall \\ |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
148 \end{tabular*} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
149 \caption{Calling convention signature encoding} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
150 \label{cconvsigchar} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
151 \end{center} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
152 \end{table} |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
153 |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
154 \pagebreak |
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
155 |
0 | 156 \paragraph{Examples of C function prototypes} |
157 | |
158 \begin{table}[h] | |
159 \begin{tabular*}{0.75\textwidth}{rll} | |
160 & C function prototype & dyncall signature \\ | |
161 \hline | |
162 void & f1(); & \sigstr{)v}\\ | |
163 int & f2(int, int); & \sigstr{ii)i}\\ | |
164 long long & f3(void*); & \sigstr{p)L}\\ | |
165 void & f3(int**); & \sigstr{p)v}\\ | |
166 double & f4(int, bool, char, double, const char*); & \sigstr{iBcdZ)d}\\ | |
490 | 167 void & f5(short, long long, ...); & \sigstr{\_esl\_.di)v} (for (promoted) varargs: double, int)\\ |
168 struct A & f6(int, union B); & \sigstr{iA)A}\\ | |
169 short & Cls::f(unsigned char, ...); & \sigstr{\_*p\_eC\_.i)A} (C++: this-ptr as 1st arg, int as vararg)\\ | |
0 | 170 \end{tabular*} |
490 | 171 \caption{Type signature examples of function prototypes} |
0 | 172 \label{sigex} |
173 \end{table} | |
174 | |
175 | |
176 | |
177 \subsection{Erlang language bindings} | |
178 | |
179 The OTP library application {\tt erldc} implements the Erlang language bindings. | |
180 | |
181 \begin{table}[h] | |
182 \begin{center} | |
183 \begin{tabular*}{0.75\textwidth}{ll} | |
184 Signature character & accepted Erlang data types\\ | |
185 \hline | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
186 \sigchar{v} & no return type\\ |
0 | 187 \sigchar{B} & atoms 'true' and 'false' converted to bool\\ |
188 \sigchar{c}, \sigchar{C} & integer cast to (unsigned) char\\ | |
189 \sigchar{s}, \sigchar{S} & integer cast to (unsigned) short\\ | |
190 \sigchar{i}, \sigchar{I} & integer cast to (unsigned) int\\ | |
191 \sigchar{j}, \sigchar{J} & integer cast to (unsigned) long\\ | |
192 \sigchar{l}, \sigchar{L} & integer cast to (unsigned) long long\\ | |
193 \sigchar{f} & decimal cast to float\\ | |
194 \sigchar{d} & decimal cast to double\\ | |
195 \sigchar{p} & binary (previously returned from call\_ptr or callf) cast to void*\\ | |
196 \sigchar{Z} & string cast to void*\\ | |
197 \end{tabular*} | |
198 \caption{Type signature encoding for Erlang bindings} | |
199 \label{Erlangsigchar} | |
200 \end{center} | |
201 \end{table} | |
202 | |
203 \pagebreak | |
204 | |
205 \subsection{Go language bindings} | |
206 | |
207 A Go binding is provided through the {\tt godc} package. Since Go's type system is basically a superset of C's, the type mapping from Go to C is straightforward. | |
208 | |
209 \begin{table}[h] | |
210 \begin{center} | |
211 \begin{tabular*}{0.75\textwidth}{ll} | |
212 Signature character & accepted Go data types\\ | |
213 \hline | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
214 \sigchar{v} & no return type\\ |
0 | 215 \sigchar{B} & bool\\ |
216 \sigchar{c}, \sigchar{C} & int8, uint8\\ | |
217 \sigchar{s}, \sigchar{S} & int16, uint16\\ | |
218 \sigchar{i}, \sigchar{I} & int, uint\\ | |
219 \sigchar{j}, \sigchar{J} & int32, uint32\\ | |
220 \sigchar{l}, \sigchar{L} & int64, uint64\\ | |
221 \sigchar{f} & float32\\ | |
222 \sigchar{d} & float64\\ | |
223 \sigchar{p}, \sigchar{Z} & uintptr, unsafe.Pointer\\ | |
224 \end{tabular*} | |
225 \caption{Type signature encoding for Go bindings} | |
226 \label{Gosigchar} | |
227 \end{center} | |
228 \end{table} | |
229 | |
230 Note that passing a Go-{\tt string} directly to a C-function expecting a pointer is not directly possible. However, the binding comes with | |
231 two helper functions, {\tt AllocCString(value string) unsafe.Pointer} and {\tt FreeCString(value unsafe.Pointer)} to help with converting | |
232 a {\tt string} to an {\tt unsafe.Pointer} which then can be passed to {\tt ArgPointer(value unsafe.Pointer)}. Once you are done with this | |
233 temporary string, free it using {\tt FreeCString(value unsafe.Pointer)}. | |
234 | |
235 | |
236 \subsection{Python language bindings} | |
237 | |
238 The python module {\tt pydc} implements the Python language bindings, | |
467 | 239 namely {\tt load}, {\tt find}, {\tt free}, {\tt call}, {\tt new\_callback}, {\tt free\_callback}. |
0 | 240 |
241 \begin{table}[h] | |
490 | 242 \begin{tabular*}{1.0\textwidth}{lll} |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
243 Signature character & accepted Python 2 types & accepted Python 3 types \\ |
0 | 244 \hline |
467 | 245 \sigchar{v} & no return type & no return type \\ |
246 \sigchar{B} & bool & bool \\ | |
247 \sigchar{c}, \sigchar{C} & int, string (with single char) & int, string (with single char) \\ | |
248 \sigchar{s}, \sigchar{S} & int & int \\ | |
249 \sigchar{i}, \sigchar{I} & int & int \\ | |
250 \sigchar{j}, \sigchar{J} & int & int \\ | |
251 \sigchar{l}, \sigchar{L} & int, long & int \\ | |
252 \sigchar{f} & float & float \\ | |
253 \sigchar{d} & float & float \\ | |
254 \sigchar{p} & bytearray, int, long, None, (PyCObject, PyCapsule) & bytearray, int, None, (PyCObject, PyCapsule) \\ | |
255 \sigchar{Z} & string, unicode, bytearray & string, bytes, bytearray \\ | |
0 | 256 \end{tabular*} |
257 \caption{Type signature encoding for Python bindings} | |
258 \label{Pysigchar} | |
259 \end{table} | |
260 | |
467 | 261 This is a very brief description that omits many details. For more, refer to the README.txt file of the binding. |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
262 |
0 | 263 \pagebreak |
264 | |
265 \subsection{R language bindings} | |
266 | |
267 The R package {\tt rdyncall} implements the R langugae bindings providing the function | |
268 {\tt .dyncall() }. | |
269 | |
270 \begin{table}[h] | |
271 \begin{center} | |
272 \begin{tabular*}{0.75\textwidth}{ll} | |
273 Signature character & accepted R data types\\ | |
274 \hline | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
275 \sigchar{v} & no return type\\ |
0 | 276 \sigchar{B} & coerced to logical vector, first item\\ |
277 \sigchar{c} & coerced to integer vector, first item truncated char\\ | |
278 \sigchar{C} & coerced to integer vector, first item truncated to unsigned char\\ | |
279 \sigchar{s} & coerced to integer vector, first item truncated to short\\ | |
280 \sigchar{S} & coerced to integer vector, first item truncated to unsigned short\\ | |
281 \sigchar{i} & coerced to integer vector, first item\\ | |
282 \sigchar{I} & coerced to integer vector, first item casted to unsigned int\\ | |
283 \sigchar{j} & coerced to integer vector, first item\\ | |
284 \sigchar{J} & coerced to integer vector, first item casted to unsigned long\\ | |
285 \sigchar{l} & coerced to numeric, first item casted to long long\\ | |
286 \sigchar{L} & coerced to numeric, first item casted to unsigned long long\\ | |
287 \sigchar{f} & coerced to numeric, first item casted to float\\ | |
288 \sigchar{d} & coerced to numeric, first item\\ | |
289 \sigchar{p} & external pointer or coerced to string vector, first item\\ | |
290 \sigchar{Z} & coerced to string vector, first item\\ | |
291 \end{tabular*} | |
292 \caption{Type signature encoding for R bindings} | |
293 \label{Rsigchar} | |
294 \end{center} | |
295 \end{table} | |
296 | |
297 Some notes on the R Binding: | |
298 \begin{itemize} | |
299 \item Unsigned 32-bit integers are represented as signed integers in R. | |
300 \item 64-bit integer types do not exist in R, therefore we use double floats | |
301 to represent 64-bit integers (using only the 52-bit mantissa part). | |
302 \end{itemize} | |
303 | |
304 \pagebreak | |
305 | |
306 \subsection{Ruby language bindings} | |
307 | |
308 The Ruby gem {\tt rbdc} implements the Ruby language bindings. | |
309 | |
310 \begin{table}[h] | |
311 \begin{center} | |
312 \begin{tabular*}{0.75\textwidth}{ll} | |
313 Signature character & accepted Ruby data types\\ | |
314 \hline | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
315 \sigchar{v} & no return type\\ |
1 | 316 \sigchar{B} & TrueClass, FalseClass, NilClass, Fixnum casted to bool\\ |
0 | 317 \sigchar{c}, \sigchar{C} & Fixnum cast to (unsigned) char\\ |
318 \sigchar{s}, \sigchar{S} & Fixnum cast to (unsigned) short\\ | |
319 \sigchar{i}, \sigchar{I} & Fixnum cast to (unsigned) int\\ | |
320 \sigchar{j}, \sigchar{J} & Fixnum cast to (unsigned) long\\ | |
321 \sigchar{l}, \sigchar{L} & Fixnum cast to (unsigned) long long\\ | |
322 \sigchar{f} & Float cast to float\\ | |
323 \sigchar{d} & Float cast to double\\ | |
324 \sigchar{p}, \sigchar{Z} & String cast to void*\\ | |
325 \end{tabular*} | |
326 \caption{Type signature encoding for Ruby bindings} | |
327 \label{Rubysigchar} | |
328 \end{center} | |
329 \end{table} | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
90
diff
changeset
|
330 |