dynbind: Binding C library functions via thin call wrappers

In rdyncall: Improved Foreign Function Interface (FFI) and Dynamic Bindings to C Libraries (e.g. OpenGL)

Description

Function to bind several foreign functions of a C library via installation of thin R call wrappers.

Usage

dynbind(libnames, signature, 
        envir=parent.frame(), callmode="default", 
        pat=NULL, replace=NULL, funcptr=FALSE)

Arguments

libnames	vector of character strings giving short library names of the shared library to be loaded. See dynfind for details.
signature	character string specifying the library signature that determines the set of foreign function names and types. See details.
envir	the environment to use for installation of call wrappers.
callmode	character string specifying the calling convention, see details.
pat	NULL or regular expression character string applied to symbolic names.
replace	NULL or replacement character string applied to pat part of symbolic names.
funcptr	logical, that indicates whether foreign objects refer to functions (FALSE, default) or to function poiner variables (TRUE rarely needed).

Details

dynbind makes a set of C functions available to R through installation of thin call wrappers. The set of functions, including the symbolic name and function type, is specified by signature ; a character string that encodes a library signature:

The library signature is a compact plain-text format to specify a set of function bindings. It consists of function names and corresponding call signatures. Function bindings are separated by ‘;’ (semicolon) ; white spaces (including tab and new line) are allowed before and after semicolon.

function-name ( call-signature ; ...

Here is an example that specifies three function bindings to the OpenGL library:

"glAccum(If)v ; glClear(I)v ; glClearColor(ffff)v ;"

Symbolic names are resolved using the library specified by libnames using dynfind for loading. For each function, a thin call wrapper function is created using the following template:

 function(...) .dyncall.<MODE> ( <TARGET>, <SIGNATURE>, ... ) 

<MODE> is replaced by callmode argument, see .dyncall for details on calling conventions. <TARGET> is replaced by the external pointer, resolved by the ‘function-name’. <SIGNATURE> is replaced by the call signature string contained in signature.

The call wrapper is installed in the environment given by envir. The assignment name is obtained from the function signature. If pat and replace is given, a text replacement is applied to the name before assignment, useful for basic C name space mangling such as exchanging the prefix.

As a special case, dynbind supports binding of pointer-to-function variables, indicated by setting funcptr to TRUE, in which case <TARGET> is replaced with the expression .unpack(<TARGET>,"p",0) in order to dereference <TARGET> as a pointer-to-function variable at call-time.

Value

The function returns a list with two fields:

libhandle	External pointer returned by .dynload.
unresolved.symbols	vector of character strings, the names of unresolved symbols.

As a side effect, for each wrapper, dynbind assigns the ‘function-name’ to the corresponding call wrapper function in the environment given by envir.

If no shared library is found, an error is reported.

See Also

.dyncall for details on call signatures and calling conventions, dynfind for details on short library names, .unpack for details on reading low-level memory (e.g. dereferencing of (function) pointer variables).

Examples

# Install two wrappers to functions of the R shared C library.
info <- dynbind("R","
R_ShowMessage(Z)v;
R_rsort(pi)v;
")
R_ShowMessage("hello")

rdyncall documentation built on May 2, 2019, 6:15 p.m.