Mercurial > pub > dyncall > dyncall
annotate doc/manual/manual_bindings.tex @ 490:17287342e273
manual:
- removed all API description and referred to manual instead, to avoid outdated and/or duplicated doc
- cleanups and clarificaions
| author | Tassilo Philipp |
|---|---|
| date | Sun, 20 Mar 2022 14:26:55 +0100 |
| parents | b47168dacba6 |
| 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 |