DeveloperInterface {BiocParallel} | R Documentation

## Developer interface

### Description

Functions documented on this page are meant for developers wishing to implement `BPPARAM` objects that extend the `BiocParallelParam` virtual class to support additional parallel back-ends.

### Usage

    ## class extension

    .prototype_update(prototype, ...)

    ## manager interface

    .send_to(backend, node, value)
    .recv_any(backend)
    .send_all(backend, value)
    .recv_all(backend)

    ## worker interface

    .send(worker, value)
    .recv(worker)
    .close(worker)

    ## supporting implementations

    .bpstart_impl(x)
    .bpworker_impl(worker)
    .bplapply_impl(X, FUN, ..., BPREDO = list(), BPPARAM = bpparam())
    .bpiterate_impl(ITER, FUN, ..., REDUCE, init, reduce.in.order = FALSE,
        BPPARAM = bpparam())
    .bpstop_impl(x)

### Arguments

`prototype` | A named `list` of default values for reference class fields.
`x` | A `BPPARAM` instance.
`backend` | An object containing information about the cluster, returned by `bpbackend(<BPPARAM>)`.
`worker` | The object to which the worker communicates via `.send` and `.recv`. `.close` terminates the worker.
`node` | An integer value indicating the node in the backend to which values are to be sent or received.
`value` | Any R object, to be sent to or from workers.
`X, ITER, FUN, REDUCE, init, reduce.in.order, BPREDO, BPPARAM` | See `bplapply` and `bpiterate`.
`...` | For `.prototype_update()`, name-value pairs to initialize derived and base class fields. For `.bplapply_impl()`, `.bpiterate_impl()`, additional arguments to `FUN()`; see `bplapply` and `bpiterate`.

### Details

Start a BPPARM implementation by creating a reference class, e.g., extending the virtual class `BiocParallelParam`. Because of idiosyncracies in reference class field initialization, an instance of the class should be created by calling the generator returned by `setRefClass()` with a list of key-value pairs providing default parameteter arguments. The default values for the `BiocParallelParam` base class is provided in a list `.BiocParallelParam_prototype`, and the function `.prototype_update()` updates a prototype with new values, typically provided by the user. See the example below.

BPPARAM implementations need to implement `bpstart()` and `bpstop()` methods; they may also need to implement, `bplapply()` and `bpiterate()` methods. Each method usually performs implementation-specific functionality before calling the next (BiocParallelParam) method. To avoid the intricacies of multiple dispatch, the bodies of BiocParallelParam methods are available for direct use as exported symbols.

- `bpstart,BiocParallelParam-method` (`.bpstart_impl()`) initiates logging, random number generation, and registration of finalizers to ensure that started clusters are stopped.

- `bpstop,BiocParallelParam-method` (`.bpstop_impl()`) ensures appropriate clean-up of stopped clusters, including sending the DONE semaphore. `bpstart()` will usually arrange for workers to enter `.bpworker_impl()` to listen for and evaluate tasks.

- `bplapply,ANY,BiocParallelParam-method` and `bpiterate,ANY,BiocParallelParam-method` (`.bplapply_impl()`, `.bpiterate_impl()`) implement: serial evaluation when there is a single core or task available; `BPREDO` functionality, and parallel lapply-like or iterative calculation.

Invoke `.bpstart_impl()`, `.bpstop_impl()`, `.bplapply_impl()`, and `.bpiterate_impl()` after any BPPARAM-specific implementation details.

New implementations will also implement `bpisup()` and `bpbackend()` / `bpbackend<-()`; there are no default methods.

The backends (object returned by `bpbackend()`) of new BPPARAM implementations must support `length()` (number of nodes). In addition, the backends must support `.send_to()` and `.recv_any()` manager and `.send()`, `.recv()`, and `.close()` worker methods. Default `.send_all()` and `.recv_all()` methods are implemented as simple iterations along the `length(cluster)`, invoking `.send_to()` or `.recv_any()` on each iteration.

### Value

The return value of `.prototype_update()` is a list with elements in `prototype` substituted with key-value pairs provided in `...`.

All `send*` and `recv*` functions are endomorphic, returning a `cluster` object.

### Examples

    ##
    ## Extend BiocParallelParam; `.A()` is not meant for the end user
    ##

    .A <- setRefClass(
        "A",
        contains = "BiocParallelParam",
        fields = list(id = "character")
    )

    ## Use a prototype for default values, including the prototype for
    ## inheritted fields

    .A_prototype <- c(
        list(id = "default_id"),
        .BiocParallelParam_prototype
    )

    ## Provide a constructor for the user

    A <- function(...) {
        prototype <- .prototype_update(.A_prototype, ...)
        do.call(.A, prototype)
    }

    ## Provide an R function for field access

    bpid <- function(x)
        x$id

    ## Create and use an instance, overwriting default values

    bpid(A())

    a <- A(id = "my_id", threshold = "WARN")
    bpid(a)
    bpthreshold(a)

[Package BiocParallel version 1.20.1 Index]