view release on metacpan or  search on metacpan

dyncall/doc/manual/manual_bindings.tex  view on Meta::CPAN

% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
%
%//////////////////////////////////////////////////////////////////////////////

\clearpage
\section{Bindings to programming languages}

Through binding of the \product{dyncall} library into a scripting environment,
the scripting language can gain system programming status to a certain degree.\\
The \product{dyncall} library provides bindings to Erlang\cite{Erlang}, Java\cite{Java},
Lua\cite{Lua}, Python\cite{Python}, R\cite{R}, Ruby\cite{Ruby}, Go\cite{Go} and the shell/command line.\\
However, please note that some of these bindings are work-in-progress and not
automatically tested, meaning it might require some additional work to make them
work.

\subsection{Common Architecture}

The binding interfaces of the \product{dyncall} library to various scripting
languages share a common set of functionality to invoke a function call.

\subsubsection{Dynamic loading of code}

The helper library \emph{dynload} which accompanies the \product{dyncall}
library provides an abstract interface to operating-system specific mechanisms
for loading and accessing executable code out of, but not limited to, shared
libraries.

\subsubsection{Functions}

All bindings are based on a common interface convention providing a common set
of the following 4 functions (exact spelling depending on the binding's scripting
environment):
\begin{description}
\item [load] - load a module of compiled code
\item [free] - unload a module of compiled code
\item [find] - find function pointer by symbolic names
\item [call] - invoke a function call
\end{description}

\pagebreak

\subsubsection{Signatures}

A signature is a character string that represents a function's arguments and
return value types. It is used in the scripting language bindings invoke
functions to perform automatic type-conversion of the languages' types to the
low-level C/C++ data types.
This is an essential part of mapping the more flexible and often abstract data
types provided in scripting languages to the strict machine-level data types
used by C-libraries.
The high-level C interface functions \capi{dcCallF()}, \capi{dcVCallF()},
\capi{dcArgF()} and \capi{dcVArgF()} of the \product{dyncall} library also make
use of this signature string format.\\
\\
The format of a \product{dyncall} signature string is as depicted below:


\paragraph{\product{dyncall} signature string format}

\begin{center}
\group{input parameter type signature character}* \sigchar{)} \group{return
type signature character} \\
\end{center}

The \group{input parameter type signature character} sequence left to the
\sigchar{)} is in left-to-right order of the corresponding C function
parameter type list.\\
The special \group{return type signature character} \sigchar{v} specifies
that the function does not return a value and corresponds to \capi{void}
functions in C.

\begin{table}[h]
\begin{center}
\begin{tabular*}{0.75\textwidth}{cl}
Signature character & C/C++ data type \\
\hline
\sigchar{v} & void \\
\sigchar{B} & \_Bool, bool \\
\sigchar{c} & char \\
\sigchar{C} & unsigned char \\
\sigchar{s} & short \\
\sigchar{S} & unsigned short \\
\sigchar{i} & int \\
\sigchar{I} & unsigned int \\
\sigchar{j} & long \\
\sigchar{J} & unsigned long \\
\sigchar{l} & long long, int64\_t \\
\sigchar{L} & unsigned long long, uint64\_t \\
\sigchar{f} & float \\
\sigchar{d} & double \\
\sigchar{p} & void* \\
\sigchar{Z} & const char* (pointing to C string) \\
\sigchar{A} & aggregate (struct, union) by-value \\
\end{tabular*}
\caption{Type signature encoding for function call data types}
\label{sigchar}
\end{center}
\end{table}

Please note that using a \sigchar{(} at the beginning of a signature string is possible,
although not required. The character doesn't have any meaning and will simply be
ignored. However, using it prevents annoying syntax highlighting problems with some code
editors.

\pagebreak

Calling convention modes can be switched using the signature string, as well. A
'\_' in the signature string is followed by a character specifying what
calling convention to use, as this affects how arguments are passed. This makes
only sense if there are multiple co-existing calling conventions on a single platform.
Usually, this is done at the beginning of the string, except in special cases, like
specifying where the varargs part of a variadic function begins.
The following signature characters exist:

\begin{table}[h]
\begin{center}
\begin{tabular*}{0.75\textwidth}{cl}
Signature character & Calling Convention \\
\hline
\sigchar{:} & platform's default calling convention \\
\sigchar{*} & platform's default C++/thiscall calling convention \\
\sigchar{e} & vararg function \\
\sigchar{.} & vararg function's variadic/ellipsis part (...), to be specified before first vararg \\
\sigchar{c} & only on x86: cdecl \\
\sigchar{s} & only on x86: stdcall \\
\sigchar{F} & only on x86: fastcall (MS) \\
\sigchar{f} & only on x86: fastcall (GNU) \\
\sigchar{+} & only on x86: thiscall (MS) \\