| % File src/library/compiler/man/compile.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2011-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{compile} |
| \alias{compile} |
| \alias{cmpfun} |
| \alias{cmpfile} |
| \alias{loadcmp} |
| \alias{disassemble} |
| \alias{enableJIT} |
| \alias{compilePKGS} |
| \alias{getCompilerOption} |
| \alias{setCompilerOptions} |
| \title{Byte Code Compiler} |
| \usage{ |
| cmpfun(f, options = NULL) |
| compile(e, env = .GlobalEnv, options = NULL, srcref = NULL) |
| cmpfile(infile, outfile, ascii = FALSE, env = .GlobalEnv, |
| verbose = FALSE, options = NULL, version = NULL) |
| loadcmp(file, envir = .GlobalEnv, chdir = FALSE) |
| disassemble(code) |
| enableJIT(level) |
| compilePKGS(enable) |
| getCompilerOption(name, options) |
| setCompilerOptions(...) |
| } |
| \arguments{ |
| \item{f}{a closure.} |
| \item{options}{list of named compiler options: see \sQuote{Details}.} |
| \item{env}{the top level environment for the compiling.} |
| \item{srcref}{initial source reference for the expression.} |
| \item{file,infile,outfile}{pathnames; outfile defaults to infile with |
| a \file{.Rc} extension in place of any existing extension.} |
| \item{ascii}{logical; should the compiled file be saved in ascii format?} |
| \item{verbose}{logical; should the compiler show what is being compiled?} |
| \item{version}{the workspace format version to use. \code{NULL} |
| specifies the current default format (3). Version 1 was the default |
| from \R 0.99.0 to \R 1.3.1 and version 2 from \R 1.4.0 to 3.5.0. |
| Version 3 is supported from \R 3.5.0.} |
| \item{envir}{environment to evaluate loaded expressions in.} |
| \item{chdir}{logical; change directory before evaluation?} |
| \item{code}{byte code expression or compiled closure} |
| \item{e}{expression to compile.} |
| \item{level}{integer; the JIT level to use (\code{0} to \code{3}).} |
| \item{enable}{logical; enable compiling packages if \code{TRUE}.} |
| \item{name}{character string; name of option to return.} |
| \item{...}{named compiler options to set.} |
| } |
| \description{ |
| These functions provide an interface to a byte code compiler for \R. |
| } |
| \details{ |
| The function \code{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. |
| |
| \code{compile} compiles an expression into a byte code object; the |
| object can then be evaluated with \code{eval}. |
| |
| \code{cmpfile} parses the expressions in \code{infile}, compiles |
| them, and writes the compiled expressions to \code{outfile}. If |
| \code{outfile} is not provided, it is formed from \code{infile} by |
| replacing or appending a \code{.Rc} suffix. |
| |
| \code{loadcmp} is used to load compiled files. It is similar to |
| \code{sys.source}, except that its default loading environment is the |
| global environment rather than the base environment. |
| |
| \code{disassemble} produces a printed representation of the code |
| that may be useful to give a hint of what is going on. |
| |
| \code{enableJIT} enables or disables just-in-time (JIT) |
| compilation. JIT is disabled if the argument is 0. If \code{level} is |
| 1 then larger closures are compiled before their first use. If |
| \code{level} is 2, then some small closures are also compiled before |
| their second use. If \code{level} is 3 then in addition |
| all top level loops are compiled before they are executed. JIT level |
| 3 requires the compiler option \code{optimize} to be 2 or 3. The JIT |
| level can also be selected by starting \R with the environment |
| variable \code{R_ENABLE_JIT} set to one of these values. Calling |
| \code{enableJIT} with a negative argument returns the current JIT |
| level. The default JIT level is \code{3}. |
| |
| \code{compilePKGS} enables or disables compiling packages when they |
| are installed. This requires that the package uses lazy loading as |
| compilation occurs as functions are written to the lazy loading data |
| base. This can also be enabled by starting \R with the environment |
| variable \code{_R_COMPILE_PKGS_} set to a positive integer value. |
| This should not be enabled outside package installation, because it |
| causes any serialized function to be compiled, which comes with |
| time and space overhead. \code{R_COMPILE_PKGS} can be used, instead, |
| to instruct \code{INSTALL} to enable/disable compilation of packages |
| during installation. |
| |
| Currently the compiler warns about a variety of things. It does |
| this by using \code{cat} to print messages. Eventually this should |
| use the condition handling mechanism. |
| |
| The \code{options} argument can be used to control compiler operation. |
| There are currently four options: \code{optimize}, \code{suppressAll}, |
| \code{suppressUndefined}, and \code{suppressNoSuperAssignVar}. |
| \code{optimize} specifies the optimization level, an integer from \code{0} |
| to \code{3} (the current out-of-the-box default is \code{2}). |
| \code{suppressAll} should be a scalar logical; if \code{TRUE} no messages |
| will be shown (this is the default). \code{suppressUndefined} can be |
| \code{TRUE} to suppress all messages about undefined variables, or it can |
| be a character vector of the names of variables for which messages should |
| not be shown. \code{suppressNoSuperAssignVar} can be \code{TRUE} to |
| suppress messages about super assignments to a variable for which no |
| binding is visible at compile time. During compilation of packages, |
| \code{suppressAll} is currently \code{FALSE}, \code{suppressUndefined} is |
| \code{TRUE} and \code{suppressNoSuperAssignVar} is \code{TRUE}. |
| |
| \code{getCompilerOption} returns the value of the specified option. |
| The default value is returned unless a value is supplied in the |
| \code{options} argument; the \code{options} argument is primarily for |
| internal use. \code{setCompilerOption} sets the default option |
| values. Options to set are identified by argument names, e.g. |
| \code{setCompilerOptions(suppressAll = TRUE, optimize = 3)}. |
| It returns a named list of the previous values. |
| |
| Calling the compiler a byte code compiler is actually a bit of a |
| misnomer: the external representation of code objects currently uses |
| \code{int} operands, and when compiled with \code{gcc} the internal |
| representation is actually threaded code rather than byte code. |
| } |
| \author{Luke Tierney} |
| |
| \examples{ |
| oldJIT <- enableJIT(0) |
| # a simple example |
| f <- function(x) x+1 |
| fc <- cmpfun(f) |
| fc(2) |
| disassemble(fc) |
| |
| # 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 |
| la1c <- cmpfun(la1) |
| la2c <- cmpfun(la2) |
| # some timings |
| x <- 1:10 |
| y <- 1:100 |
| \donttest{ |
| 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)) |
| } |
| \testonly{ |
| for (i in 1:10000) lapply(x, is.null) |
| for (i in 1:10000) la1(x, is.null) |
| for (i in 1:10000) la1c(x, is.null) |
| for (i in 1:10000) la2(x, is.null) |
| for (i in 1:10000) la2c(x, is.null) |
| for (i in 1:1000) lapply(y, is.null) |
| for (i in 1:1000) la1(y, is.null) |
| for (i in 1:1000) la1c(y, is.null) |
| for (i in 1:1000) la2(y, is.null) |
| for (i in 1:1000) la2c(y, is.null) |
| } |
| enableJIT(oldJIT)} |
| \keyword{programming} |