share {SharedObject} | R Documentation

## Create a shared object

### Description

This function will create a shared object in the shared memory for the object `x`. There is no duplication of the shared object when it is exported to the other processes.

### Usage

    share(x, ...)

    ## S4 method for signature 'ANY'
    share(x, ..., copyOnWrite, sharedSubset, sharedCopy, mustWork)

### Arguments

`x` | An R object that you want to shared, see details.
`...` | For generalization purpose.
`copyOnWrite, sharedSubset, sharedCopy` | The parameters controlling the behavior of the shared object, see details.
`mustWork` | Whether to throw an error if `x` is not a sharable object(e.g. Character). This parameter has no effect on the S4 object.

### Details

The function returns a shared object corresponding to the argument `x` if it is sharable. There should be no different between `x` and the return value except that the latter one is shared. The attribute(s) of `x` will also be shared.

Supported types

For the basic R types, the function supports `raw`,`logical` ,`integer`, `double`, `complex`. `character` cannot be shared for it has a complicated data structure and closely relates to R's cache. For the containers, the function supports `list`, `pairlist` and `environment`. Note that sharing a container is equivalent sharing all elements in the container, the container itself will not be shared.

The function `share` is an S4 generic. The default share method works for most S4 objects. Therefore, there is no need to define a S4 share method for each S4 class unless the S4 class has a special implementation(e.g. on-disk data). The default method will share the object itself and all slots it contains. No error will be given if any of these objects are not sharable and they will be kept unchanged.

Behavior control

In the R level, the behaviors of an ALTREP object is exactly the same as an atomic object but the data of an ALTREP object is allocated in the shared memory space. Therefore an ALTREP object can be easily exported to the other R processes without dulplicating the data, which reduces the memory usage and the overhead of data transmission.

The behavior of a shared object can be controlled through three parameters: `copyOnWrite`, `sharedSubset` and `sharedCopy`.

`copyOnWrite` determines Whether a new R object need to be allocated when the shared object is changed. The default value is `TRUE`, but can be altered by passing an argument `copyOnWrite = FALSE` to the function.

Please note that the no-copy-on-write feature is not fully supported by R. When `copyOnWrite` is `FALSE`, a shared object might not behaves as user expects. Please refer to the example code to see the exceptions.

`sharedSubset` determines whether the subset of a shared object is still a shared object. The default value is `FALSE`, and can be changed by passing `sharedSubset = TRUE` to the function

At the time this documentation is being written, The shared subset feature will cause an unnecessary memory duplication in R studio. Therefore, for the performance consideration, it is better to turn the feature off when using R studio.

`sharedCopy` determines whether the object is still a shared object after a duplication. If `copyOnWrite` is `FALSE`, this feature is off since the duplication cannot be triggered. In current version (R 3.6), an object will be duplicated four times for creating a shared object and lead to a serious performance problem. Therefore, the default value is `FALSE`, user can alter it by passing `sharedCopy = FALSE` to the function.

### Value

A shared object

### Examples

    ## For vector
    x <- runif(10)
    so <- share(x)
    x
    so

    ## For matrix
    x <- matrix(runif(10), 2, 5)
    so <- share(x)
    x
    so

    ## For data frame
    x <- as.data.frame(matrix(runif(10), 2, 5))
    so <- share(x)
    x
    so

    ## export the object
    library(parallel)
    cl <- makeCluster(1)
    clusterExport(cl, "so")
    ## check the exported object in the other process
    clusterEvalQ(cl, so)

    ## close the connection
    stopCluster(cl)

    ## Copy-on-write
    ## This is the default setting
    x <- runif(10)
    so1 <- share(x, copyOnWrite = TRUE)
    so2 <- so1
    so2[1] <- 10
    ## so1 is unchanged since copy-on-write feature is on.
    so1
    so2

    ## No-copy-on-write
    so1 <- share(x, copyOnWrite = FALSE)
    so2 <- so1
    so2[1] <- 10
    #so1 is changed
    so1
    so2

    ## Flaw of no-copy-on-write
    ## The following code changes the value of so1, highly unexpected! Please use with caution!
    -so1
    so1
    ## The reason is that the minus function trys to dulplicate so1 object,
    ## but the dulplicate function will return so1 itself, so the value in so1 also get changed.

[Package SharedObject version 1.4.0 Index]