Package 'quickr'

Description

This will compile all quick() functions in an R package, and generate source files in the ⁠src/⁠ directory.

Usage

compile_package(path = ".")

Arguments

Details

Note, this function is automatically invoked during a pkgload::load_all() call.

Value

Called for its side effect.

Description

Compile an R function.

Usage

quick(fun, name = NULL)

Arguments

Details

declare(type()) syntax:

The shape and mode of all function arguments must be declared. Local and return variables may optionally also be declared.

declare(type()) also has support for declaring size constraints, or size relationships between variables. Here are some examples of declare calls:

declare(type(x = double(NA))) # x is a 1-d double vector of any length
declare(type(x = double(10))) # x is a 1-d double vector of length 10
declare(type(x = double(1)))  # x is a scalar double

declare(type(x = integer(2, 3)))  # x is a 2-d integer matrix with dim (2, 3)
declare(type(x = integer(NA, 3))) # x is a 2-d integer matrix with dim (<any>, 3)

# x is a 4-d logical matrix with dim (<any>, 24, 24, 3)
declare(type(x = logical(NA, 24, 24, 3)))

# x and y are 1-d double vectors of any length
declare(type(x = double(NA)),
        type(y = double(NA)))

# x and y are 1-d double vectors of the same length
declare(
  type(x = double(n)),
  type(y = double(n)),
)

# x and y are 1-d double vectors, where length(y) == length(x) + 2
declare(type(x = double(n)),
        type(y = double(n+2)))

You can provide declarations to declare() as:

• Multiple arguments to a single declare() call

• Separate declare() calls

• Multiple arguments within a code block ({}) inside declare()

declare(
  type(x = double(n)),
  type(y = double(n)),
)

declare(type(x = double(n)))
declare(type(y = double(n)))

declare({
  type(x = double(n))
  type(y = double(n))
})

Return values

The shape and type of a function return value must be known at compile time. In most situations, this will be automatically inferred by quick(). However, if the output is dynamic, then you may need to provide a hint. For example, returning the result of seq() will fail because the output shape cannot be inferred.

# Will fail to compile:
quick_seq <- quick(function(start, end) {
  declare({
    type(start = integer(1))
    type(end = integer(1))
  })
  out <- seq(start, end)
  out
})

However, if the output size can be declared as a dynamic expression using other values known at runtime, compilation will succeed:

# Succeeds:
quick_seq <- quick(function(start, end) {
  declare({
    type(start = integer(1))
    type(end = integer(1))
    type(out = integer(end - start + 1))
  })
  out <- seq(start, end)
  out
})
quick_seq(1L, 5L)

Fortran compiler

quickr compiles via ⁠R CMD SHLIB⁠ and will normally use the same toolchain that R was built/configured with.

quickr only uses LLVM flang when it is explicitly requested or, on macOS, when flang is available on PATH (and flang --version succeeds). If flang is requested but unavailable, compilation errors. If flang compilation fails, quickr retries with the default toolchain; on success it emits a one-time warning and disables automatic flang preference for the rest of the session.

In interactive use, you can explicitly control this with:

options(quickr.fortran_compiler = "flang")

To disable the macOS auto-preference, set options(quickr.fortran_compiler = "gfortran").

Value

A quicker R function.

Examples

add_ab <- quick(function(a, b) {
  declare(type(a = double(n)),
          type(b = double(n)))
  a + b
})
add_ab(1, 2)
add_ab(c(1, 2, 3), c(4, 5, 6))