developer-API: Functions to manipulate shared memory

In Jiefei-Wang/SharedObject: Sharing R objects across multiple R processes without memory duplication

Functions to manipulate shared memory

Description

These functions are designed for package developers only, they can allocate, open, close and destroy shared memory without touching C++ code. Normal users should not use these functions unless dealing with memory leaking

Usage

getLastIndex()

allocateSharedMemory(size, name = "")

mapSharedMemory(id)

unmapSharedMemory(id)

freeSharedMemory(id)

hasSharedMemory(id)

getSharedMemorySize(id)

initialSharedObjectPackageData()

releaseSharedObjectPackageData()

Arguments

size	The size of the shared memory that you want to allocate
name, id	The name of the shared memory

Details

Quick explanation

getLastIndex: the ID of the last created shared memory.

allocateSharedMemory: allocate a shared memory of a given size, the memory ID is returned by the function

mapSharedMemory: map the shared memory to the current process memory space

unmapSharedMemory: unmap the shared memory(without destroying it)

freeSharedMemory: free the shared memory. This function will only unmap the shared memory on Windows.

hasSharedMemory: whether the memory exist?

getSharedMemorySize: get the actual size of the shared memory, it may be larger than the size that you required.

Details

A complete lifecycle of a shared memory involves four steps: allocating, mapping, unmapping and freeing the shared memory.

The shared memory can be created by allocateSharedMemory. The function allocateSharedMemory will return the ID of the shared memory. After creating the shared memory, it can be mapped to the current process by mapSharedMemory. The return value is an external pointer to the shared memory. Once the shared memory is no longer needed, it can be unmapped and destroyed by unmapSharedMemory and freeSharedMemory respectively.

Value

getLastIndex: An interger ID served as a hint of the last created shared memory ID.

allocateSharedMemory: character ID(s) that can be used to find the shared memory

mapSharedMemory: External pointer(s) to the shared memory

unmapSharedMemory: No return value

freeSharedMemory: No return value

hasSharedMemory: Logical value(s) indicating whether the shared memory exist

getSharedMemorySize: A numeric value

See Also

listSharedObjects

Examples

size <- 10L
## unnamed shared memory
id <- allocateSharedMemory(size)
hasSharedMemory(id)
ptr <- mapSharedMemory(id)
ptr
getSharedMemorySize(id)
unmapSharedMemory(id)
freeSharedMemory(id)
hasSharedMemory(id)

## named shared memory
name <- "SharedObjectExample"
if(!hasSharedMemory(name)){
    allocateSharedMemory(size, name = name)
    hasSharedMemory(name)
    ptr <- mapSharedMemory(name)
    ptr
    getSharedMemorySize(name)
    unmapSharedMemory(name)
    freeSharedMemory(name)
    hasSharedMemory(name)
}

Jiefei-Wang/SharedObject documentation built on Aug. 19, 2023, 5:47 p.m.