register {BiocParallel} | R Documentation

## Maintain a global registry of available back-end Params

### Description

Use functions on this page to add to or query a registry of back-ends, including the default for use when no `BPPARAM` object is provided to functions.

### Usage

    register(BPPARAM, default=TRUE)
    registered(bpparamClass)
    bpparam(bpparamClass)

### Arguments

`BPPARAM` | An instance of a `BiocParallelParam` class, e.g., `MulticoreParam`, `SnowParam`, `DoparParam`.
`default` | Make this the default `BiocParallelParam` for subsequent evaluations? If `FALSE`, the argument is placed at the lowest priority position.
`bpparamClass` | When present, the text name of the `BiocParallelParam` class (e.g., “MulticoreParam”) to be retrieved from the registry. When absent, a list of all registered instances is returned.

### Details

The registry is a list of back-ends with configuration parameters for parallel evaluation. The first list entry is the default and is used by `BiocParallel` functions when no `BPPARAM` argument is supplied.

At load time the registry is populated with default backends. On Windows these are `SnowParam` and `SerialParam` and on non-Windows `MulticoreParam`, `SnowParam` and `SerialParam`. When `snowWorkers()` or `multicoreWorkers` returns a single core, only `SerialParm` is registered.

The `BiocParallelParam` objects are constructed from global options of the corresponding name, or from the default constructor (e.g., `SnowParam()`) if no option is specified. The user can set customizations during start-up (e.g., in an `.Rprofile` file) with, for instance, `options(MulticoreParam=quote(MulticoreParam(workers=8)))`.

The act of “registering” a back-end modifies the existing `BiocParallelParam` in the list; only one param of each type can be present in the registry. When `default=TRUE`, the newly registered param is moved to the top of the list thereby making it the default. When `default=FALSE`, the param is modified 'in place' vs being moved to the top.

`bpparam()`, invoked with no arguments, returns the default `BiocParallelParam` instance from the registry. When called with the text name of a `bpparamClass`, the global options are consulted first, e.g., `options(MulticoreParam=MulticoreParam())` and then the value of `registered(bpparamClass)`.

### Value

`register` returns, invisibly, a list of registered back-ends.

`registered` returns the back-end of type `bpparamClass` or, if `bpparamClass` is missing, a list of all registered back-ends.

`bpparam` returns the back-end of type `bpparamClass` or,

### Author(s)

Martin Morgan mailto:mtmorgan@fhcrc.org.

### See Also

`BiocParallelParam` for possible values of `BPPARAM`.

### Examples

    ## ----------------------------------------------------------------------
    ## The registry
    ## ----------------------------------------------------------------------

    ## The default registry.
    default <- registered()
    default

    ## When default = TRUE the last param registered becomes the new default.
    snowparam <- SnowParam(workers = 3, type = "SOCK")
    register(snowparam, default = TRUE)
    registered()

    ## Retrieve the default back-end,
    bpparam()

    ## or a specific BiocParallelParam.
    bpparam("SnowParam")

    ## restore original registry -- push the defaults in reverse order
    for (param in rev(default))
        register(param)

    ## ----------------------------------------------------------------------
    ## Specifying a back-end for evaluation
    ## ----------------------------------------------------------------------

    ## The back-end of choice is given as the BPPARAM argument to
    ## the BiocParallel functions. None, one, or multiple back-ends can be
    ## used.

    bplapply(1:6, sqrt, BPPARAM = MulticoreParam(3))

    ## When not specified, the default from the registry is used.
    bplapply(1:6, sqrt)

[Package BiocParallel version 1.21.2 Index]