|
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
|
|
|
20 \newpage
|
|
|
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
|
|
|
62 low-level C/C++ data types. This is an essential part of mapping the more flexible
|
|
|
63 and often abstract data types provided in scripting languages conveniently to the
|
|
|
64 strict machine-level data types used by C-libraries.
|
|
|
65 The high-level C interface functions \capi{dcCallF()}, \capi{dcVCallF()},
|
|
|
66 \capi{dcArgF()} and \capi{dcVArgF()} of the \product{dyncall} library also make
|
|
|
67 use of this signature string format.\\
|
|
|
68 \\
|
|
|
69 The format of a \product{dyncall} signature string is as depicted below:
|
|
|
70
|
|
|
71
|
|
|
72 \paragraph{\product{dyncall} signature string format}
|
|
|
73
|
|
|
74 \begin{center}
|
|
|
75 \group{input parameter type signature character}* \sigchar{)} \group{return
|
|
|
76 type signature character} \\
|
|
|
77 \end{center}
|
|
|
78
|
|
|
79 The \group{input parameter type signature character} sequence left to the
|
|
|
80 \sigchar{)} is in left-to-right order of the corresponding C function
|
|
|
81 parameter type list.\\
|
|
|
82 The special \group{return type signature character} \sigchar{v} specifies
|
|
|
83 that the function does not return a value and corresponds to \capi{void}
|
|
|
84 functions in C.
|
|
|
85
|
|
|
86 \begin{table}[h]
|
|
|
87 \begin{center}
|
|
|
88 \begin{tabular*}{0.75\textwidth}{cl}
|
|
|
89 \hline
|
|
|
90 Signature character & C/C++ data type \\
|
|
|
91 \hline
|
|
|
92 \sigchar{B} & \_Bool, bool \\
|
|
|
93 \sigchar{c} & char \\
|
|
|
94 \sigchar{C} & unsigned char \\
|
|
|
95 \sigchar{s} & short \\
|
|
|
96 \sigchar{S} & unsigned short \\
|
|
|
97 \sigchar{i} & int \\
|
|
|
98 \sigchar{I} & unsigned int \\
|
|
|
99 \sigchar{j} & long \\
|
|
|
100 \sigchar{J} & unsigned long \\
|
|
|
101 \sigchar{l} & long long, int64\_t \\
|
|
|
102 \sigchar{L} & unsigned long long, uint64\_t \\
|
|
|
103 \sigchar{f} & float \\
|
|
|
104 \sigchar{d} & double \\
|
|
|
105 \sigchar{p} & void* \\
|
|
|
106 \sigchar{Z} & const char* (pointing to C string) \\
|
|
|
107 \sigchar{v} & void \\
|
|
|
108 \hline
|
|
|
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
|
|
|
122 \paragraph{Examples of C function prototypes}
|
|
|
123
|
|
|
124 \begin{table}[h]
|
|
|
125 \begin{center}
|
|
|
126 \begin{tabular*}{0.75\textwidth}{rll}
|
|
|
127 \hline
|
|
|
128 & C function prototype & dyncall signature \\
|
|
|
129 \hline
|
|
|
130 void & f1(); & \sigstr{)v}\\
|
|
|
131 int & f2(int, int); & \sigstr{ii)i}\\
|
|
|
132 long long & f3(void*); & \sigstr{p)L}\\
|
|
|
133 void & f3(int**); & \sigstr{p)v}\\
|
|
|
134 double & f4(int, bool, char, double, const char*); & \sigstr{iBcdZ)d}\\
|
|
|
135 \hline
|
|
|
136 \end{tabular*}
|
|
|
137 \caption{Type signature examples of C function prototypes}
|
|
|
138 \label{sigex}
|
|
|
139 \end{center}
|
|
|
140 \end{table}
|
|
|
141
|
|
|
142
|
|
|
143
|
|
|
144 \subsection{Erlang language bindings}
|
|
|
145
|
|
|
146 The OTP library application {\tt erldc} implements the Erlang language bindings.
|
|
|
147
|
|
|
148 \begin{table}[h]
|
|
|
149 \begin{center}
|
|
|
150 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
151 \hline
|
|
|
152 Signature character & accepted Erlang data types\\
|
|
|
153 \hline
|
|
|
154 \sigchar{B} & atoms 'true' and 'false' converted to bool\\
|
|
|
155 \sigchar{c}, \sigchar{C} & integer cast to (unsigned) char\\
|
|
|
156 \sigchar{s}, \sigchar{S} & integer cast to (unsigned) short\\
|
|
|
157 \sigchar{i}, \sigchar{I} & integer cast to (unsigned) int\\
|
|
|
158 \sigchar{j}, \sigchar{J} & integer cast to (unsigned) long\\
|
|
|
159 \sigchar{l}, \sigchar{L} & integer cast to (unsigned) long long\\
|
|
|
160 \sigchar{f} & decimal cast to float\\
|
|
|
161 \sigchar{d} & decimal cast to double\\
|
|
|
162 \sigchar{p} & binary (previously returned from call\_ptr or callf) cast to void*\\
|
|
|
163 \sigchar{Z} & string cast to void*\\
|
|
|
164 \sigchar{v} & no return type\\
|
|
|
165 \hline
|
|
|
166 \end{tabular*}
|
|
|
167 \caption{Type signature encoding for Erlang bindings}
|
|
|
168 \label{Erlangsigchar}
|
|
|
169 \end{center}
|
|
|
170 \end{table}
|
|
|
171
|
|
|
172 \pagebreak
|
|
|
173
|
|
|
174 \subsection{Go language bindings}
|
|
|
175
|
|
|
176 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.
|
|
|
177
|
|
|
178 \begin{table}[h]
|
|
|
179 \begin{center}
|
|
|
180 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
181 \hline
|
|
|
182 Signature character & accepted Go data types\\
|
|
|
183 \hline
|
|
|
184 \sigchar{B} & bool\\
|
|
|
185 \sigchar{c}, \sigchar{C} & int8, uint8\\
|
|
|
186 \sigchar{s}, \sigchar{S} & int16, uint16\\
|
|
|
187 \sigchar{i}, \sigchar{I} & int, uint\\
|
|
|
188 \sigchar{j}, \sigchar{J} & int32, uint32\\
|
|
|
189 \sigchar{l}, \sigchar{L} & int64, uint64\\
|
|
|
190 \sigchar{f} & float32\\
|
|
|
191 \sigchar{d} & float64\\
|
|
|
192 \sigchar{p}, \sigchar{Z} & uintptr, unsafe.Pointer\\
|
|
|
193 \sigchar{v} & no return type\\
|
|
|
194 \hline
|
|
|
195 \end{tabular*}
|
|
|
196 \caption{Type signature encoding for Go bindings}
|
|
|
197 \label{Gosigchar}
|
|
|
198 \end{center}
|
|
|
199 \end{table}
|
|
|
200
|
|
|
201 Note that passing a Go-{\tt string} directly to a C-function expecting a pointer is not directly possible. However, the binding comes with
|
|
|
202 two helper functions, {\tt AllocCString(value string) unsafe.Pointer} and {\tt FreeCString(value unsafe.Pointer)} to help with converting
|
|
|
203 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
|
|
|
204 temporary string, free it using {\tt FreeCString(value unsafe.Pointer)}.
|
|
|
205
|
|
|
206
|
|
|
207 \subsection{Python language bindings}
|
|
|
208
|
|
|
209 The python module {\tt pydc} implements the Python language bindings,
|
|
|
210 namely {\tt load}, {\tt find}, {\tt free}, {\tt call}.
|
|
|
211
|
|
|
212 \begin{table}[h]
|
|
|
213 \begin{center}
|
|
|
214 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
215 \hline
|
|
|
216 Signature character & accepted Python data types\\
|
|
|
217 \hline
|
|
|
218 \sigchar{B} & bool \\
|
|
|
219 \sigchar{c} & if string, take first item\\
|
|
|
220 \sigchar{s} & int, check in range\\
|
|
|
221 \sigchar{i} & int\\
|
|
|
222 \sigchar{j} & int\\
|
|
|
223 \sigchar{l} & long, casted to long long\\
|
|
|
224 \sigchar{f} & float\\
|
|
|
225 \sigchar{d} & double\\
|
|
|
226 \sigchar{p} & string or long casted to void*\\
|
|
|
227 \sigchar{v} & no return type\\
|
|
|
228 \hline
|
|
|
229 \end{tabular*}
|
|
|
230 \caption{Type signature encoding for Python bindings}
|
|
|
231 \label{Pysigchar}
|
|
|
232 \end{center}
|
|
|
233 \end{table}
|
|
|
234
|
|
|
235 \pagebreak
|
|
|
236
|
|
|
237 \subsection{R language bindings}
|
|
|
238
|
|
|
239 The R package {\tt rdyncall} implements the R langugae bindings providing the function
|
|
|
240 {\tt .dyncall() }.
|
|
|
241
|
|
|
242 \begin{table}[h]
|
|
|
243 \begin{center}
|
|
|
244 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
245 \hline
|
|
|
246 Signature character & accepted R data types\\
|
|
|
247 \hline
|
|
|
248 \sigchar{B} & coerced to logical vector, first item\\
|
|
|
249 \sigchar{c} & coerced to integer vector, first item truncated char\\
|
|
|
250 \sigchar{C} & coerced to integer vector, first item truncated to unsigned char\\
|
|
|
251 \sigchar{s} & coerced to integer vector, first item truncated to short\\
|
|
|
252 \sigchar{S} & coerced to integer vector, first item truncated to unsigned short\\
|
|
|
253 \sigchar{i} & coerced to integer vector, first item\\
|
|
|
254 \sigchar{I} & coerced to integer vector, first item casted to unsigned int\\
|
|
|
255 \sigchar{j} & coerced to integer vector, first item\\
|
|
|
256 \sigchar{J} & coerced to integer vector, first item casted to unsigned long\\
|
|
|
257 \sigchar{l} & coerced to numeric, first item casted to long long\\
|
|
|
258 \sigchar{L} & coerced to numeric, first item casted to unsigned long long\\
|
|
|
259 \sigchar{f} & coerced to numeric, first item casted to float\\
|
|
|
260 \sigchar{d} & coerced to numeric, first item\\
|
|
|
261 \sigchar{p} & external pointer or coerced to string vector, first item\\
|
|
|
262 \sigchar{Z} & coerced to string vector, first item\\
|
|
|
263 \sigchar{v} & no return type\\
|
|
|
264 \hline
|
|
|
265 \end{tabular*}
|
|
|
266 \caption{Type signature encoding for R bindings}
|
|
|
267 \label{Rsigchar}
|
|
|
268 \end{center}
|
|
|
269 \end{table}
|
|
|
270
|
|
|
271 Some notes on the R Binding:
|
|
|
272 \begin{itemize}
|
|
|
273 \item Unsigned 32-bit integers are represented as signed integers in R.
|
|
|
274 \item 64-bit integer types do not exist in R, therefore we use double floats
|
|
|
275 to represent 64-bit integers (using only the 52-bit mantissa part).
|
|
|
276 \end{itemize}
|
|
|
277
|
|
|
278 \pagebreak
|
|
|
279
|
|
|
280 \subsection{Ruby language bindings}
|
|
|
281
|
|
|
282 The Ruby gem {\tt rbdc} implements the Ruby language bindings.
|
|
|
283
|
|
|
284 \begin{table}[h]
|
|
|
285 \begin{center}
|
|
|
286 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
287 \hline
|
|
|
288 Signature character & accepted Ruby data types\\
|
|
|
289 \hline
|
|
1
|
290 \sigchar{B} & TrueClass, FalseClass, NilClass, Fixnum casted to bool\\
|
|
0
|
291 \sigchar{c}, \sigchar{C} & Fixnum cast to (unsigned) char\\
|
|
|
292 \sigchar{s}, \sigchar{S} & Fixnum cast to (unsigned) short\\
|
|
|
293 \sigchar{i}, \sigchar{I} & Fixnum cast to (unsigned) int\\
|
|
|
294 \sigchar{j}, \sigchar{J} & Fixnum cast to (unsigned) long\\
|
|
|
295 \sigchar{l}, \sigchar{L} & Fixnum cast to (unsigned) long long\\
|
|
|
296 \sigchar{f} & Float cast to float\\
|
|
|
297 \sigchar{d} & Float cast to double\\
|
|
|
298 \sigchar{p}, \sigchar{Z} & String cast to void*\\
|
|
|
299 \sigchar{v} & no return type\\
|
|
|
300 \hline
|
|
|
301 \end{tabular*}
|
|
|
302 \caption{Type signature encoding for Ruby bindings}
|
|
|
303 \label{Rubysigchar}
|
|
|
304 \end{center}
|
|
|
305 \end{table}
|
