Consider the getrusage example in the examples
directory.
Specifically, let's look at the gettimeofday
routine.
int gettimeofday(struct timeval *tv, struct timezone *tz);
When we look at this routine, we can "recognize"
that the two arguments are out arguments.
We might want to call this in several different ways from
R.
gettimeofday()
no arguments and we just want two values back
representing the contents of the timeval and timezone structures.
In this case, the C code could use local variables
and explicitly copy them back to R objects.
An alternative approach is that again the R users calls
the function with no arguments, but the R function
allocates C-level structures for these two arguments and
then passes the references to the C routine that calls
gettimeofday.
gettimeofday =
function()
{
tv = alloc("struct timeval")
tz = alloc("struct timezone")
.Call(R_gettimeofday, tv, tz)
}
The C routine R_gettimeofday is then defined as
SEXP
R_gettimeofday(SEXP r_tv, SEXP r_tz)
{
SEXP ans;
struct timeval *tv;
struct timezone *tz;
tv = DEREF_PTR(r_tv, struct timeval);
tz = DEREF_PTR(r_tz, struct timezone);
gettimeofday(tv, tz);
PROTECT(ans = NEW_LIST(2));
SET_VECTOR_ELT(ans, 0, r_tv);
SET_VECTOR_ELT(ans, 1, r_tz);
/* Put names on the elements of the list ... */
UNPROTECT(1);
return(ans);
}
This just gets access to the allocated data structures
and passes them to gettimeofday and then, with the structures filled in, passes the two
back as a list. We could do the last step in R.
Alternatively, we could explicitly copy the contents as before
rather than returning references.
But again, we can do this in R, either in the R function
or leaving it to the user
as(gettimeofday()[[1]], "timeval")
So we have several combinations.
Create the local variables in C and copy the results back to R
objects.
Create the local variables from R as references and pass
them to C to be filled in and then either copy them back as R objects
or return as references to the C data structures and fetch the
invdividual elements as needed.
And the C code would look like
A simple example
I have put together a simple, artificial example
that allows us to test some of this in different ways.
We start with C code
which defines two routines which are very similar
with one calling the other.
The difference is that the second one returns an integer.
The first returns nothing.
Both routines take an integer and then two out arguments.
", '"RConverters.h"'))
writeCode(B, "native", file = con )
writeCode(bindings, "native", file = con )
close(con)
con = file("/tmp/Routargs.R", "w")
writeCode(A, "r", file = con )
writeCode(B, "r", file = con )
writeCode(bindings, "r", file = con )
close(con)
]]>
cd tmp
R CMD SHLIB outargs.c Routargs.c RConverters.c
dyn.load("/tmp/outargs.so")
source("/tmp/Routargs.R")
myInt(10, NULL, NULL)
myInt(10)
myInt(10, .copy = c('a' = NA, 'b' = NA))
myInt(10, NULL, NULL, .copy = c('a' = FALSE, 'b' = FALSE))
myVoid(10)
myVoid(10, .copy = c(a=TRUE, b= NA))
We now test the finalizers
a = new_A(.finalizer = TRUE)
a$x = 10
a$y = 20.4
as(a, "A")
aa = as(as(a, "A"), "ARef")
b = new_B(.finalizer = TRUE)
as(b, "B")
rm(a,b)
gc()
Now to check explicit freeing.
a = new_A()
Free(a)
We need to work with more complex examples
where we have pointers to other things
and can exercise the recursive facility.
Copying Results back to R
We introduce the support for default values for out arguments.
We also allow the user to specify which values to copy
to R and which to leave as references and which to ignore
entirely via the .copy parameter.
We can implement this in R or we can do it more succinctly
in C.
Let's look at the myInt example.
We would end up with code like the following
0 ? r_a : R_copyStruct_A( &a ) );
SET_STRING_ELT(r_names, r_ctr++, mkChar("a"));
}
if(LOGICAL(r__copy)[1] != NA_LOGICAL) {
SET_VECTOR_ELT( r_ans, r_ctr , LOGICAL(r__copy)[1] == FALSE && GET_LENGTH( r_b ) > 0 ? r_b : R_copyStruct_A( &b ) );
SET_STRING_ELT(r_names, r_ctr++, mkChar("b"));
}
SET_NAMES(r_ans, r_names);
UNPROTECT( 2 );
]]>