ipcmutex {BiocParallel} | R Documentation

## Inter-process locks and counters

### Description

Functions documented on this page enable locks and counters between processes on the same computer.

Use `ipcid()` to generate a unique mutex or counter identifier. A mutex or counter with the same `id`, including those in different processes, share the same state.

`ipcremove()` removes external state associated with mutex or counters created with `id`.

`ipclock()` blocks until the lock is obtained. `ipctrylock()` tries to obtain the lock, returning immediately if it is not available. `ipcunlock()` releases the lock. `ipclocked()` queries the lock to determine whether it is currently held.

`ipcyield()` returns the current counter, and increments the value for subsequent calls. `ipcvalue()` returns the current counter without incrementing. `ipcreset()` sets the counter to `n`, such that the next call to `ipcyield()` or `ipcvalue()` returns `n`.

### Usage

    ## Utilities

    ipcid(id)

    ipcremove(id)

    ## Locks

    ipclock(id)

    ipctrylock(id)

    ipcunlock(id)

    ipclocked(id)

    ## Counters

    ipcyield(id)

    ipcvalue(id)

    ipcreset(id, n = 1)

### Arguments

`id` | character(1) identifier string for mutex or counter. `ipcid()` ensures that the identifier is universally unique.
`n` | integer(1) value from which `ipcyield()` will increment.

### Value

Locks:

`ipclock()` creates a named lock, returning `TRUE` on success.

`trylock()` returns `TRUE` if the lock is obtained, `FALSE` otherwise.

`ipcunlock()` returns `TRUE` on success, `FALSE` (e.g., because there is nothing to unlock) otherwise.

`ipclocked()` returns `TRUE` when `id` is locked, and `FALSE` otherwise.

Counters:

`ipcyield()` returns an integer(1) value representing the next number in sequence. The first value returned is 1.

`ipcvalue()` returns the value to be returned by the next call to `ipcyield()`, without incrementing the counter. If the counter is no longer available, `ipcyield()` returns `NA`.

`ipcreset()` returns `n`, invisibly.

Utilities:

`ipcid()` returns a character(1) unique identifier, with `id` (if not missing) prepended.

`ipcremove()` returns (invisibly) `TRUE` if external resources were released or `FALSE` if not (e.g., because the resources has already been released).

### Examples

    ipcid()

    ## Locks

    id <- ipcid()

    ipclock(id)
    ipctrylock(id)
    ipcunlock(id)
    ipctrylock(id)
    ipclocked(id)

    ipcremove(id)

    id <- ipcid()
    system.time({
        ## about 1s, .2s for each process instead of .2s if no lock
        result <- bplapply(1:2, function(i, id) {
            BiocParallel::ipclock(id)
            Sys.sleep(.2)
            time <- Sys.time()
            BiocParallel::ipcunlock(id)
            time
        }, id)
    })
    ipcremove(id)
    diff(sort(unlist(result, use.names=FALSE)))

    ## Counters

    id <- ipcid()

    ipcyield(id)
    ipcyield(id)

    ipcvalue(id)
    ipcyield(id)

    ipcreset(id, 10)
    ipcvalue(id)
    ipcyield(id)

    ipcremove(id)

    id <- ipcid()
    result <- bplapply(1:2, function(i, id) {
        BiocParallel::ipcyield(id)
    }, id)
    ipcremove(id)
    sort(unlist(result, use.names=FALSE))

[Package BiocParallel version 1.20.1 Index]