memshare (version 1.1.0)

retrieveViews: Function to obtain an 'ALTREP' representation of variables from a shared memory space.

Description

Given a namespace identifier (identifies the shared memory space to register to), this function constructs mocked matrices/vectors (depending on the variable type) pointing to 'C++' shared memory instead of 'R'-internal memory state. The mockup is constructed as an 'ALTREP' object, which is an Rcpp wrapper around 'C++' raw memory. 'R' thinks of these objects as common matrices or vectors.

The variables content can be modified, resulting in modification of shared memory. Thus when not using wrapper functions like memApply or memLapply the user has to be cautious of the side-effects an 'R' session working on shared memory has on other 'R' sessions working on the same namespace.

Usage

retrieveViews(namespace, variableNames)

Value

An 1:p list of p elements, each element contains a variable that was registered by registerVariables

Arguments

namespace

string of the identifier of the shared memory context.

variableNames

[1:n] character vector, the names of the variables to retrieve from the shared memory space.

Author

Julian Maerte

Details

Thread safety

Returned objects may alias shared memory. Concurrent writes must be synchronized externally (e.g., interprocess mutex). Do not call the R API from secondary threads.

Resource cleanup

Each call must be matched by releaseViews. Failing to release views prevents releaseVariables from freeing memory.

See Also

releaseVariables, registerVariables, releaseViews

Examples

  if (FALSE) { 
  # MASTER SESSION:
  # init some data and make shared
  }
  n = 1000
  m = 100

  mat = matrix(rnorm(n * m), n, m) # target matrix
  y = rnorm(n) # some other constant vector in which the function should not run

  namespace = "ns_retrview"
  memshare::registerVariables(namespace, list(mat=mat, y=y))
  if (FALSE) {
  # WORKER SESSION
  # retrieve the shared data and work with it
  }
  res = memshare::retrieveViews(namespace, c("mat", "y"))
  if (FALSE) {
  # res is a list of the format:
  # list(mat=matrix_altrep, y=vector_altrep),
  # altrep-variables can be used
  # exactly the same way as a matrix or vector
  # and also behave like them when checking via
  # is.matrix or is.numeric.


  # important: Free view before resuming
  # to master session to release the variables!
  }
  memshare::releaseViews(namespace, c("mat", "y"))
  
  if (FALSE) {
  # MASTER SESSION
  # After all view handles have been free'd, release the variable
  }
  memshare::releaseVariables(namespace, c("mat", "y"))