[Rcpp-devel] Rcpp modules documentation

[Dirk Eddelbuettel]

There had been a number of posts over the last few weeks (months?) where
folks were struggling with getting Rcpp modules going based on the examples
in the vignette.  

I just spent a few hours cleaning things up.  The gist of it is

  -- this always worked, but I often forgot to point out that loading
     a module is different when you use inline to compile/load on the fly,
     and when you use a package;

  -- both uses were in fact documented in the vignette;

  -- both uses were in fact used in the unit tests too;

but it was a little hard to get to.  Now with the cleanup:: 

  -- the unit test for Rcpp modules actually had three different modules which
     I commented a bit more, and also moved to the package created by

        Rcpp.package.skeleton("somePackageName, module=TRUE)

     to provide more direct examples

  -- I moved some things from the 'evaluate but do not show' mode of Sweave
     into full view, so the vignette should be a tad more helpful as well.


So in short, "on the fly" and via inline's cxxfunction, one can do 

     inc <- '
     using namespace Rcpp;
     
     double norm( double x, double y ) {
         return sqrt( x*x + y*y );
     }
     
     RCPP_MODULE(mod) {
         function( "norm", &norm );
     }
     '
     library(inline)
     fx <- cxxfunction(, plugin="Rcpp", include=inc)
     
     mod <- Module( "mod", getDynLib(fx) )
     mod$norm( 3, 4 )

     
where the key is to pass the object created by cxxfunction() to Module() via
the getDynLib() function.  Free functions such as 'norm' are then accessible
as member functions of the object created by Module().

In a package, things are different.  We now declare the modules we want in
DESCRIPTION, and these can be loaded for us on startup -- the
skeleton-generated package shows how.  Free functions (such as norm above)
appear directly in the namespace of the package -- so it would be norm(3,4).

For "normal" use of Rcpp modules where classes are created we have

  -- via cxxfunction the following three-step:

        mod_vec <- Module( "mod_vec", getDynLib(fx_vec), mustStart = TRUE )
        vec <- mod_vec$vec
        v <- new( vec )

     which a) instantiated the module via Module(), b) gets the class from
     the modules and c) call the constructor via new()

  -- via a properly-created package it is just 

        v <- new( vec )

     as module is instantiated at package load.

All this is in SVN on R-Forge; the Rcpp package revision is now 0.9.10.5.

And with this we should be reasonably close to a 0.9.11 release.  There is a
bit more which John Chambers contributed not so long ago --- and which is
quite exciting as it builds on this and permits extending C++ classes on fly
from the R side with new member functions --- which I should document for
both a new release and the upcoming Rcpp tutorial at useR.

Hope this helps,  Dirk

-- 
Dirk Eddelbuettel | edd at debian.org | http://dirk.eddelbuettel.com