The R language defines two different types of functions: primitive functions, which are low-level, and closures, which are the regular kind of functions.
is_function(x) is_closure(x) is_primitive(x) is_primitive_eager(x) is_primitive_lazy(x)
| x | Object to be tested. |
|---|
Closures are functions written in R, named after the way their
arguments are scoped within nested environments (see
https://en.wikipedia.org/wiki/Closure_(computer_programming)). The
root environment of the closure is called the closure
environment. When closures are evaluated, a new environment called
the evaluation frame is created with the closure environment as
parent. This is where the body of the closure is evaluated. These
closure frames appear on the evaluation stack (see ctxt_stack()),
as opposed to primitive functions which do not necessarily have
their own evaluation frame and never appear on the stack.
Primitive functions are more efficient than closures for two
reasons. First, they are written entirely in fast low-level
code. Second, the mechanism by which they are passed arguments is
more efficient because they often do not need the full procedure of
argument matching (dealing with positional versus named arguments,
partial matching, etc). One practical consequence of the special
way in which primitives are passed arguments is that they
technically do not have formal arguments, and formals() will
return NULL if called on a primitive function. Finally, primitive
functions can either take arguments lazily, like R closures do,
or evaluate them eagerly before being passed on to the C code.
The former kind of primitives are called "special" in R terminology,
while the latter is referred to as "builtin". is_primitive_eager()
and is_primitive_lazy() allow you to check whether a primitive
function evaluates arguments eagerly or lazily.
You will also encounter the distinction between primitive and
internal functions in technical documentation. Like primitive
functions, internal functions are defined at a low level and
written in C. However, internal functions have no representation in
the R language. Instead, they are called via a call to
base::.Internal() within a regular closure. This ensures that
they appear as normal R function objects: they obey all the usual
rules of argument passing, and they appear on the evaluation stack
as any other closures. As a result, fn_fmls() does not need to
look in the .ArgsEnv environment to obtain a representation of
their arguments, and there is no way of querying from R whether
they are lazy ('special' in R terminology) or eager ('builtin').
You can call primitive functions with .Primitive() and internal
functions with .Internal(). However, calling internal functions
in a package is forbidden by CRAN's policy because they are
considered part of the private API. They often assume that they
have been called with correctly formed arguments, and may cause R
to crash if you call them with unexpected objects.
# Primitive functions are not closures: is_closure(base::c) #> [1] FALSE is_primitive(base::c) #> [1] TRUE # On the other hand, internal functions are wrapped in a closure # and appear as such from the R side: is_closure(base::eval) #> [1] TRUE # Both closures and primitives are functions: is_function(base::c) #> [1] TRUE is_function(base::eval) #> [1] TRUE # Primitive functions never appear in evaluation stacks: is_primitive(base::`[[`) #> [1] TRUE is_primitive(base::list) #> [1] TRUE list(ctxt_stack())[[1]] #> [[1]] #> <frame 35> (34) #> expr: eval(expr, envir, enclos) #> env: [local 0x560eb2127658] #> #> [[2]] #> <frame 34> (24) #> expr: eval(expr, envir, enclos) #> env: [local 0x560eb378d5b0] #> #> [[3]] #> <frame 33> (24) #> expr: withVisible(eval(expr, envir, enclos)) #> env: [local 0x560eb378d7e0] #> #> [[4]] #> <frame 32> (24) #> expr: withCallingHandlers(withVisible(eval(expr, envir, enclos)), warning = wHandler, <...> #> env: [local 0x560eb378dd90] #> #> [[5]] #> <frame 31> (30) #> expr: doTryCatch(return(expr), name, parentenv, handler) #> env: [local 0x560eb378e308] #> #> [[6]] #> <frame 30> (29) #> expr: tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> env: [local 0x560eb378e650] #> #> [[7]] #> <frame 29> (28) #> expr: tryCatchList(expr, classes, parentenv, handlers) #> env: [local 0x560eb378e998] #> #> [[8]] #> <frame 28> (27) #> expr: tryCatch(expr, error = function(e) { <...> #> env: [local 0x560eb3789310] #> #> [[9]] #> <frame 27> (26) #> expr: try(f, silent = TRUE) #> env: [local 0x560eb3789540] #> #> [[10]] #> <frame 26> (24) #> expr: handle(ev <- withCallingHandlers(withVisible(eval(expr, envir, <...> #> env: [local 0x560eb37896c8] #> #> [[11]] #> <frame 25> (24) #> expr: timing_fn(handle(ev <- withCallingHandlers(withVisible(eval(expr, <...> #> env: [local 0x560eb37897a8] #> #> [[12]] #> <frame 24> (23) #> expr: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, <...> #> env: [frame 0x560eb11c0830] #> #> [[13]] #> <frame 23> (22) #> expr: evaluate::evaluate(code, child_env(env), new_device = TRUE, output_handler = output_handler) #> env: [frame 0x560eb213ef58] #> #> [[14]] #> <frame 22> (21) #> expr: downlit::evaluate_and_highlight(code, fig_save = fig_save_topic, <...> #> env: [frame 0x560eb213c7e8] #> #> [[15]] #> <frame 21> (20) #> expr: highlight_examples(code, topic, env = env) #> env: [frame 0x560eb21367e8] #> #> [[16]] #> <frame 20> (19) #> expr: run_examples(tags$tag_examples[[1]], env = new.env(parent = globalenv()), <...> #> env: [frame 0x560eb04de9c8] #> #> [[17]] #> <frame 19> (17) #> expr: data_reference_topic(topic, pkg, examples = examples, run_dont_run = run_dont_run) #> env: [frame 0x560eb00c0ee0] #> #> [[18]] #> <frame 18> (17) #> expr: withCallingHandlers(data_reference_topic(topic, pkg, examples = examples, <...> #> env: [frame 0x560eb00c1618] #> #> [[19]] #> <frame 17> (16) #> expr: .f(.x[[i]], ...) #> env: [frame 0x560eb0939fe0] #> #> [[20]] #> <frame 16> (15) #> expr: purrr::map(topics, build_reference_topic, pkg = pkg, lazy = lazy, <...> #> env: [frame 0x560eade2f628] #> #> [[21]] #> <frame 15> (14) #> expr: build_reference(pkg, lazy = lazy, examples = examples, run_dont_run = run_dont_run, <...> #> env: [frame 0x560eab934750] #> #> [[22]] #> <frame 14> (13) #> expr: build_site_local(pkg = pkg, examples = examples, run_dont_run = run_dont_run, <...> #> env: [frame 0x560eaacff240] #> #> [[23]] #> <frame 13> (12) #> expr: pkgdown::build_site(...) #> env: [frame 0x560eaac4a318] #> #> [[24]] #> <frame 12> (0) #> expr: (function (..., crayon_enabled, crayon_colors, pkgdown_internet) <...> #> env: [frame 0x560eab586628] #> #> [[25]] #> <frame 11> (0) #> expr: (function (what, args, quote = FALSE, envir = parent.frame()) <...> #> env: [frame 0x560eab580200] #> #> [[26]] #> <frame 10> (0) #> expr: do.call(do.call, c(readRDS("/tmp/RtmpVTMEEO/callr-fun-e127c12e3e3"), <...> #> env: [frame 0x560eaab35d48] #> #> [[27]] #> <frame 9> (0) #> expr: saveRDS(do.call(do.call, c(readRDS("/tmp/RtmpVTMEEO/callr-fun-e127c12e3e3"), <...> #> env: [frame 0x560eaab36138] #> #> [[28]] #> <frame 8> (0) #> expr: withCallingHandlers({ <...> #> env: [frame 0x560eaab36988] #> #> [[29]] #> <frame 7> (6) #> expr: doTryCatch(return(expr), name, parentenv, handler) #> env: [frame 0x560eaab331e8] #> #> [[30]] #> <frame 6> (5) #> expr: tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> env: [frame 0x560eaab33530] #> #> [[31]] #> <frame 5> (2) #> expr: tryCatchList(expr, names[-nh], parentenv, handlers[-nh]) #> env: [frame 0x560eaab338e8] #> #> [[32]] #> <frame 4> (3) #> expr: doTryCatch(return(expr), name, parentenv, handler) #> env: [frame 0x560eaab33e98] #> #> [[33]] #> <frame 3> (2) #> expr: tryCatchOne(tryCatchList(expr, names[-nh], parentenv, handlers[-nh]), <...> #> env: [frame 0x560eaab341e0] #> #> [[34]] #> <frame 2> (1) #> expr: tryCatchList(expr, classes, parentenv, handlers) #> env: [frame 0x560eaab34528] #> #> [[35]] #> <frame 1> (0) #> expr: tryCatch(withCallingHandlers({ <...> #> env: [frame 0x560eaab34c60] #> #> [[36]] #> <frame 0> [global] #> expr: NULL #> env: [global] #> #> attr(,"class") #> [1] "ctxt_stack" "stack" # While closures do: identity(identity(ctxt_stack())) #> [[1]] #> <frame 37> (35) #> expr: identity(ctxt_stack()) #> env: [local 0x560eb12d7748] #> #> [[2]] #> <frame 36> (35) #> expr: identity(identity(ctxt_stack())) #> env: [local 0x560eb12d7860] #> #> [[3]] #> <frame 35> (34) #> expr: eval(expr, envir, enclos) #> env: [local 0x560eb2127658] #> #> [[4]] #> <frame 34> (24) #> expr: eval(expr, envir, enclos) #> env: [local 0x560eb12d7a20] #> #> [[5]] #> <frame 33> (24) #> expr: withVisible(eval(expr, envir, enclos)) #> env: [local 0x560eb12d7c50] #> #> [[6]] #> <frame 32> (24) #> expr: withCallingHandlers(withVisible(eval(expr, envir, enclos)), warning = wHandler, <...> #> env: [local 0x560eb12d43d0] #> #> [[7]] #> <frame 31> (30) #> expr: doTryCatch(return(expr), name, parentenv, handler) #> env: [local 0x560eb12d4948] #> #> [[8]] #> <frame 30> (29) #> expr: tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> env: [local 0x560eb12d4c90] #> #> [[9]] #> <frame 29> (28) #> expr: tryCatchList(expr, classes, parentenv, handlers) #> env: [local 0x560eb12d4fd8] #> #> [[10]] #> <frame 28> (27) #> expr: tryCatch(expr, error = function(e) { <...> #> env: [local 0x560eb12d56a0] #> #> [[11]] #> <frame 27> (26) #> expr: try(f, silent = TRUE) #> env: [local 0x560eb12d58d0] #> #> [[12]] #> <frame 26> (24) #> expr: handle(ev <- withCallingHandlers(withVisible(eval(expr, envir, <...> #> env: [local 0x560eb12d5a58] #> #> [[13]] #> <frame 25> (24) #> expr: timing_fn(handle(ev <- withCallingHandlers(withVisible(eval(expr, <...> #> env: [local 0x560eb12d5b38] #> #> [[14]] #> <frame 24> (23) #> expr: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, <...> #> env: [frame 0x560eb1eeb780] #> #> [[15]] #> <frame 23> (22) #> expr: evaluate::evaluate(code, child_env(env), new_device = TRUE, output_handler = output_handler) #> env: [frame 0x560eb213ef58] #> #> [[16]] #> <frame 22> (21) #> expr: downlit::evaluate_and_highlight(code, fig_save = fig_save_topic, <...> #> env: [frame 0x560eb213c7e8] #> #> [[17]] #> <frame 21> (20) #> expr: highlight_examples(code, topic, env = env) #> env: [frame 0x560eb21367e8] #> #> [[18]] #> <frame 20> (19) #> expr: run_examples(tags$tag_examples[[1]], env = new.env(parent = globalenv()), <...> #> env: [frame 0x560eb04de9c8] #> #> [[19]] #> <frame 19> (17) #> expr: data_reference_topic(topic, pkg, examples = examples, run_dont_run = run_dont_run) #> env: [frame 0x560eb00c0ee0] #> #> [[20]] #> <frame 18> (17) #> expr: withCallingHandlers(data_reference_topic(topic, pkg, examples = examples, <...> #> env: [frame 0x560eb00c1618] #> #> [[21]] #> <frame 17> (16) #> expr: .f(.x[[i]], ...) #> env: [frame 0x560eb0939fe0] #> #> [[22]] #> <frame 16> (15) #> expr: purrr::map(topics, build_reference_topic, pkg = pkg, lazy = lazy, <...> #> env: [frame 0x560eade2f628] #> #> [[23]] #> <frame 15> (14) #> expr: build_reference(pkg, lazy = lazy, examples = examples, run_dont_run = run_dont_run, <...> #> env: [frame 0x560eab934750] #> #> [[24]] #> <frame 14> (13) #> expr: build_site_local(pkg = pkg, examples = examples, run_dont_run = run_dont_run, <...> #> env: [frame 0x560eaacff240] #> #> [[25]] #> <frame 13> (12) #> expr: pkgdown::build_site(...) #> env: [frame 0x560eaac4a318] #> #> [[26]] #> <frame 12> (0) #> expr: (function (..., crayon_enabled, crayon_colors, pkgdown_internet) <...> #> env: [frame 0x560eab586628] #> #> [[27]] #> <frame 11> (0) #> expr: (function (what, args, quote = FALSE, envir = parent.frame()) <...> #> env: [frame 0x560eab580200] #> #> [[28]] #> <frame 10> (0) #> expr: do.call(do.call, c(readRDS("/tmp/RtmpVTMEEO/callr-fun-e127c12e3e3"), <...> #> env: [frame 0x560eaab35d48] #> #> [[29]] #> <frame 9> (0) #> expr: saveRDS(do.call(do.call, c(readRDS("/tmp/RtmpVTMEEO/callr-fun-e127c12e3e3"), <...> #> env: [frame 0x560eaab36138] #> #> [[30]] #> <frame 8> (0) #> expr: withCallingHandlers({ <...> #> env: [frame 0x560eaab36988] #> #> [[31]] #> <frame 7> (6) #> expr: doTryCatch(return(expr), name, parentenv, handler) #> env: [frame 0x560eaab331e8] #> #> [[32]] #> <frame 6> (5) #> expr: tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> env: [frame 0x560eaab33530] #> #> [[33]] #> <frame 5> (2) #> expr: tryCatchList(expr, names[-nh], parentenv, handlers[-nh]) #> env: [frame 0x560eaab338e8] #> #> [[34]] #> <frame 4> (3) #> expr: doTryCatch(return(expr), name, parentenv, handler) #> env: [frame 0x560eaab33e98] #> #> [[35]] #> <frame 3> (2) #> expr: tryCatchOne(tryCatchList(expr, names[-nh], parentenv, handlers[-nh]), <...> #> env: [frame 0x560eaab341e0] #> #> [[36]] #> <frame 2> (1) #> expr: tryCatchList(expr, classes, parentenv, handlers) #> env: [frame 0x560eaab34528] #> #> [[37]] #> <frame 1> (0) #> expr: tryCatch(withCallingHandlers({ <...> #> env: [frame 0x560eaab34c60] #> #> [[38]] #> <frame 0> [global] #> expr: NULL #> env: [global] #> #> attr(,"class") #> [1] "ctxt_stack" "stack" # Many primitive functions evaluate arguments eagerly: is_primitive_eager(base::c) #> [1] TRUE is_primitive_eager(base::list) #> [1] TRUE is_primitive_eager(base::`+`) #> [1] TRUE # However, primitives that operate on expressions, like quote() or # substitute(), are lazy: is_primitive_lazy(base::quote) #> [1] TRUE is_primitive_lazy(base::substitute) #> [1] TRUE