retrieveViews: Function to obtain an "ALTREP" representation of variables...

In memshare: Shared Memory Multithreading

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)

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.

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.

Value

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

Note

Having a view of a memory chunk introduces an internally tracked handle to the shared memory. Shared memory is not deleted until all handles are gone; before calling releaseVariables in the master session, you have to free all view-initialized handles via releaseViews!

Author(s)

Julian Maerte

See Also

releaseVariables, registerVariables, releaseViews

Examples

  ## Not run:  
  # MASTER SESSION:
  # init some data and make shared
  
## End(Not run)
  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))
  ## Not run: 
  # WORKER SESSION
  # retrieve the shared data and work with it
  
## End(Not run)
  res = memshare::retrieveViews(namespace, c("mat", "y"))
  ## Not run: 
  # 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!
  
## End(Not run)
  memshare::releaseViews(namespace, c("mat", "y"))
  
  ## Not run: 
  # MASTER SESSION
  # After all view handles have been free'd, release the variable
  
## End(Not run)
  memshare::releaseVariables(namespace, c("mat", "y"))

memshare documentation built on Dec. 5, 2025, 9:07 a.m.