compile               package:compiler               R Documentation

Byte Code Compiler

Description:

     These functions provide an interface to a byte code compiler for
     R.

Usage:

     cmpfun(f, env = NULL)
     cmpfile(infile, outfile, ascii = FALSE, env = .GlobalEnv)
     compile(e, env=NULL, promise = FALSE)
     loadcmp(file, envir = .GlobalEnv, chdir = FALSE) 
     disassemble(code)

Arguments:

       f: a closure.

     env: for 'cmpfun' a static environment description; not yet useful
          at top level. For 'cmpfile' the top level environment for the
          compiled file.

file,infile,outfile: pathnames; outfile defaults to infile with a .Rc
          extension in place of any existing extension.

   ascii: logical; should the compiled file be saved with in ascii
          format?

 promise: logical; not yet useful at top level.

   envir: environment to evaluate loaded expressions in.

   chdir: logical; change directory before evaluation?

    code: byte code expression or compiled closure

       e: expression to compile

Details:

     The function 'cmpfun' compiles the body of a closure and returns a
     new closure with the same formals and the body replaced by the
     compiled body expression.

     'cmpfile' parses the expression in 'infile', compiles them, and
     writes the compiled expressions to 'outfile'.  If 'outfile' is not
     provided, it is formed from 'infile' by replacing or appending a
     '.Rc' suffix.

     'compile' compiles an expression into a byte code object; the
     object can then be evaluated with 'eval'.  'compile' is mainly
     used inside the compiler itself; it might be useful on its own,
     but I'm not sure.  It may be removed from the public interface

     'loadcmp' is used to load compiled files.  It is similar to
     'sys.source', except that its default loading environment is the
     global environment rather than the base environment.

     'disassemble' produces a printed representation of the code that
     may be useful to give a hint of what is going on.

     Currently the compiler warns about a variety of things.  It does
     this by using 'cat' to print messages.  Eventually this should use
     the condition handling mechanism.

     The compiler does not make use of the name space mechanism yet. It
     assumes that global functions with certain names are the ones
     defined in base.  This can cause trouble if code is intended to
     use a finction defined in a package or the global environment that
     shadows one defined in base.

     Calling the compiler a byte code compiler is actually a bit of a
     misnomer: the external representation of code objects currently
     uses 'int' operands, and when compiled with 'gcc' the internal
     representation is actually threaded code rather than byte code.

Author(s):

     Luke Tierney

Examples:

     # a simple example
     f <- function(x) x+1
     fc <- cmpfun(f)
     fc(2)  # result is 3
     disassemble(fc)
     # result is :
     # list(.Code, list(4, GETVAR.OP, 1, LDCONST.OP, 2, ADD.OP, RETURN.OP), 
     #      list(x + 1, x, 1))

     # old R version of lapply
     la1 <- function(X, FUN, ...) {
         FUN <- match.fun(FUN)
         if (!is.list(X))
             X <- as.list(X)
         rval <- vector("list", length(X))
         for(i in seq(along = X))
             rval[i] <- list(FUN(X[[i]], ...))
         names(rval) <- names(X)               # keep `names' !
         return(rval)
     }
     # a small variation
     la2 <- function(X, FUN, ...) {
         FUN <- match.fun(FUN)
         if (!is.list(X))
             X <- as.list(X)
         rval <- vector("list", length(X))
         for(i in seq(along = X)) {
             v <- FUN(X[[i]], ...)
             if (is.null(v)) rval[i] <- list(v)
             else rval[[i]] <- v
         }
         names(rval) <- names(X)               # keep `names' !
         return(rval)
     }
     # Compiled versions (uncompiled 10 times slower than lapply; compiled 7 times slower)
     la1c <- cmpfun(la1)
     la2c <- cmpfun(la2)
     # some timings
     x<-1:10
     y<-1:100
     system.time(for (i in 1:10000) lapply(x, is.null))
     system.time(for (i in 1:10000) la1(x, is.null))
     system.time(for (i in 1:10000) la1c(x, is.null))
     system.time(for (i in 1:10000) la2(x, is.null))
     system.time(for (i in 1:10000) la2c(x, is.null))
     system.time(for (i in 1:1000) lapply(y, is.null))
     system.time(for (i in 1:1000) la1(y, is.null))
     system.time(for (i in 1:1000) la1c(y, is.null))
     system.time(for (i in 1:1000) la2(y, is.null))
     system.time(for (i in 1:1000) la2c(y, is.null))