R/options.R

In basilisk: Freezing Python Dependencies Inside Bioconductor Packages

#' Options for \pkg{basilisk}
#'
#' Options controlling the efficiency and friendliness of starting up a Python instance via \pkg{basilisk}.
#'
#' @param value Logical scalar:
#' \itemize{
#' \item For \code{setBasiliskFork}, whether forking should be used when available.
#' \item For \code{setBasiliskShared}, whether the shared Python instance can be set in the R session.
#' }
#'
#' @return
#' All functions return a logical scalar indicating whether the specified option is enabled.
#'
#' @details
#' By default, \code{\link{basiliskStart}} will attempt to load a shared Python instance into the R session.
#' This avoids the overhead of setting up a new process but will potentially break any \pkg{reticulate}-dependent code outside of \pkg{basilisk}.
#' To guarantee that non-\pkg{basilisk} code can continue to execute, users can set \code{setBasiliskShared(FALSE)}.
#' This will load the Python instance into a self-contained \pkg{basilisk} process.
#'
#' If a new process must be generated by \code{\link{basiliskStart}}, forking is used by default.
#' This is generally more efficient than socket communication when it is available (i.e., not on Windows),
#' but can be less efficient if any garbage collection occurs inside the new process.
#' In such cases, users or developers may wish to turn off forking with \code{setBasiliskFork(FALSE)},
#' e.g., in functions where many R-based memory allocations are performed inside \code{\link{basiliskRun}}.
#'
#' If many \pkg{basilisk}-dependent packages are to be used together on Unix systems, setting \code{setBasiliskShared(FALSE)} may be beneficial.
#' This allows each package to fork to create a new process as no Python has been loaded in the parent R process (see \code{?\link{basiliskStart}}).
#' In contrast, if any package loads Python sharedly, the others are forced to use parallel socket processes.
#' This results in a tragedy of the commons where the efficiency of all other packages is reduced.
#' 
#' @author Aaron Lun
#' @examples
#' getBasiliskFork()
#' getBasiliskShared()
#' 
#' @seealso
#' \code{\link{basiliskStart}}, where these options are used.
#' @export
#' @rdname basiliskOptions
getBasiliskFork <- function() {
    globals$get("fork")
}

#' @export
#' @rdname basiliskOptions
setBasiliskFork <- function(value) {
    .check_logical(value)
    globals$set(fork=value)
    value
}

#' @export
#' @rdname basiliskOptions
getBasiliskShared <- function() {
    globals$get("shared")
}

#' @export
#' @rdname basiliskOptions
setBasiliskShared <- function(value) {
    .check_logical(value)
    globals$set(shared=value)
    value
}

.check_logical <- function(value) {
    if (length(value)!=1 || is.na(value)) {
        stop("'value' should be a non-NA logical scalar")
    }
}