defStructClass: Generate R code to work with a C-level struct

In omegahat/RGCCTUFFI: Programmatically generate interfaces to C routines and data structures that are accessed dynamically via Rffi

Description

This function and its methods generate the R code to interface to a C-level struct. It creates classes to parallel the struct in R or to maintain a reference to a C-level instance of the struct. It generates methods for $ and [[ to access fields within a reference to the struct, and also a method for the names function to return the names of the fields for a reference to a C instance of the struct. The function provides coercion methods from a reference to the R representation (by copying the fields into slots in the R object), and from a simple pointer to the R classes (reference and R-level representation). This also creates a constructor function to create an instance of the R-level class. The function also creates an FFI description of the structure for use with accessing the individual fields or specifying the struct as an input or output type of a C routine so that the routine can be invoked via callCIF.

Usage

defStructClass(type, name = type@name, ref = TRUE, 
                refClassName = getRRefTypeName(type), 
               useGlobalFFIType = useClosure, useClosure = TRUE)

Arguments

type	the GCC TU description of the C struct type. This must be resolved
name	the name of the structure
ref	whether to create code for the reference class
refClassName	the name of the reference class. By default we append Ref to the end of the name of the regular R representation class.
useGlobalFFIType	a logical value controlling whether we put the FFI description of the struct in a global variable and refer to that or put it in a closure to be used locally within each function.
useClosure	a logical value controlling whether to create functions with their own environments so that they can refer to the FFI type and symbol addresses locally rather than polluting the search path.

Value

A list with code for the different aspects of the interface.

defs	class definitions
dollar	for the $ and [[ accessor functions
coerce	coercion code, i.e. the as methods
constructors	code for the constructor function
names	function returing the field names of a reference to the struct

Author(s)

Duncan Temple Lang

References

The RGCCTranslationUnit. libffi

See Also

RCReference-class setClass $

Examples

  tu.file = system.file("TU", "utsname", "utsname.c.001t.tu", package =  "RGCCTUFFI")

  tu = parseTU(tu.file)
  r = getRoutines(tu)
  r.uname = resolveType(r$uname, tu)
  code = createRFunc(r.uname, returnInputs = "FALSE")

  ds = getDataStructures(tu)
  ds.utsname = resolveType(ds$utsname, tu)
  scode = defStructClass(ds.utsname)

  define(list(code, scode))

  u = utsnameRef()
  uname(u)

  names(u)
  u[]
  u$sysname


  ################ 
  # Alternatively, we can use genTUInterface() to do everything
  # for us in a single call.  But we lose some control, e.g.
  # setting the returnInputs.

  code = genTUInterface(tu.file, pattern = "utsname|uname")

      # now we can evaluate/load/define the code in this R session
      # including the uname() function.
  define(code)

omegahat/RGCCTUFFI documentation built on May 24, 2019, 1:53 p.m.