basiliskOptions: Options for 'basilisk'
In LTLA/jormungandR: Freezing Python Dependencies Inside Bioconductor Packages

getBasiliskFork

R Documentation

Options for basilisk

Description

Options controlling run-time behavior of basilisk. Unlike the various environment variables, these options can be turned on or off by users without requiring reinstallation of the basilisk ecosystem.

Usage

getBasiliskFork()

setBasiliskFork(value)

getBasiliskShared()

setBasiliskShared(value)

getBasiliskForceFallback()

setBasiliskForceFallback(value)

setBasiliskCheckVersions(value)

getBasiliskCheckVersions()

Arguments

value

Logical scalar:

For setBasiliskFork, whether forking should be used when available.
For setBasiliskShared, whether the shared Python instance can be set in the R session.
For setBasiliskForceFallback, whether to force the use of the last resort fallback.
For setBasiliskCheckVersions, whether to check for properly versioned package strings in setupBasiliskEnv.

Value

All functions return a logical scalar indicating whether the specified option is enabled.

Controlling process creation

By default, 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 reticulate-dependent code outside of basilisk. To guarantee that non-basilisk code can continue to execute, users can set setBasiliskShared(FALSE). This will load the Python instance into a self-contained basilisk process.

If a new process must be generated by 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 setBasiliskFork(FALSE), e.g., in functions where many R-based memory allocations are performed inside basiliskRun.

If many basilisk-dependent packages are to be used together on Unix systems, setting 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 ?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.

Developers may wish to set setBasiliskShared(FALSE) and setBasiliskFork(FALSE) during unit testing, to ensure that their functions do not make incorrect assumptions about the calling environment used in basiliskRun. Similarly, setting setBasiliskForceFallback(TRUE) is useful for testing that basiliskRun works inside a minimalistic R installation.

Disabling package version checks

By default, setupBasiliskEnv requires versions for all requested Python packages. However, in some cases, the exact version of the packages may not be known beforehand. Developers can set setBasiliskCheckVersions(FALSE) to disable all version checks, instead allowing conda to choose appropriate versions for the initial installation. The resulting environment can then be queried using listPackages to obtain the explicit versions of all Python packages.

Needless to say, this option should only be used during the initial phases of developing a basilisk client. Once a suitable environment is created by conda, Python package versions should be pinned in setupBasiliskEnv. This ensures that all users are creating the intended environment for greater reproducibility (and easier debugging).