| Title: | Shared Memory for R Objects |
| Version: | 0.1.0 |
| Description: | Share R objects across processes on the same machine via a single copy in 'POSIX' shared memory (Linux, macOS) or a 'Win32' file mapping (Windows). Every process reads from the same physical pages through the R Alternative Representation ('ALTREP') framework, giving lazy, zero-copy access. Shared objects serialize compactly as their shared memory name rather than their full contents. |
| License: | MIT + file LICENSE |
| URL: | https://shikokuchuo.net/mori/, https://github.com/shikokuchuo/mori |
| BugReports: | https://github.com/shikokuchuo/mori/issues |
| Depends: | R (≥ 4.3) |
| Suggests: | lobstr, mirai, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| NeedsCompilation: | yes |
| RoxygenNote: | 7.3.3 |
| Packaged: | 2026-04-19 21:32:08 UTC; cg334 |
| Author: | Charlie Gao  [aut,
cre],
Posit Software, PBC  [cph,
fnd] |
| Maintainer: | Charlie Gao <charlie.gao@posit.co> |
| Repository: | CRAN |
| Date/Publication: | 2026-04-21 20:12:15 UTC |
mori: Shared Memory for R Objects
Description
Share R objects via shared memory with share(), access them in
other processes with map_shared(), using R's ALTREP framework for
zero-copy memory-mapped access. Shared objects serialize compactly
via ALTREP serialization hooks. Shared memory is automatically freed
when the R object is garbage collected.
Author(s)
Maintainer: Charlie Gao charlie.gao@posit.co (ORCID)
Other contributors:
Posit Software, PBC (ROR) [copyright holder, funder]
See Also
Useful links:
Report bugs at https://github.com/shikokuchuo/mori/issues
Test if an Object is Shared
Description
Returns TRUE if x is an ALTREP object backed by shared memory
(created by share() or map_shared()), FALSE otherwise.
Usage
is_shared(x)
Arguments
x |
an R object. |
Value
TRUE or FALSE.
Examples
x <- share(rnorm(100))
is_shared(x)
is_shared(rnorm(100))
Open Shared Memory by Name
Description
Open a shared memory region identified by a name string and return an ALTREP-backed R object that reads directly from shared memory.
Usage
map_shared(name)
Arguments
name |
a character string name identifying the shared memory
region, as returned by |
Value
The R object stored in the shared memory region, or NULL if
name is not a valid shared memory name (wrong type, length, NA,
or missing the mori prefix). If name is well-formed but the
region is absent or corrupted, an error is raised.
See Also
share() to create a shared object, shared_name() to
extract the name.
Examples
x <- share(1:100)
nm <- shared_name(x)
y <- map_shared(nm)
sum(y)
Create a Shared Object
Description
Write an R object into shared memory and return a version that other processes on the same machine can map without copying.
Usage
share(x)
Arguments
x |
an R object. |
Details
Attributes are stored alongside the data in the shared memory region
and restored on the consumer side. Character vectors use a packed
layout and elements are materialised lazily on access. When serialised
(e.g. by serialize() or across a mirai() call), a
shared object is represented compactly by its SHM name (~30 bytes)
rather than by its contents.
The shared memory region is managed automatically. It stays alive as long as the returned object (or any element extracted from it) is referenced in R, and is freed by the garbage collector when no references remain.
share() is idempotent: calling it on an object that is already
backed by shared memory returns the input unchanged without
allocating a new region.
Important: always assign the result of share() to a
variable. The shared memory is kept alive by the R object reference —
if the result is used as a temporary (not assigned), the garbage
collector may free the shared memory before a consumer process has
mapped it.
Value
For atomic vectors (including character vectors and those with
attributes such as names, dim, class, or levels) and lists or data
frames whose elements are such vectors, an ALTREP-backed object that
reads directly from shared memory. For any other object (environments,
closures, language objects, NULL), the input is returned
unchanged with no shared memory region created.
See Also
map_shared() to open a shared region by name,
shared_name() to extract the SHM name.
Examples
x <- share(rnorm(100))
sum(x)
Extract Shared Memory Name
Description
Extract the SHM region name from a shared object. This name can be
passed to map_shared() to open the same region in another process.
Usage
shared_name(x)
Arguments
x |
a shared object as returned by |
Value
A character string identifying the shared memory region, or
the empty string "" if x is not a shared object.
See Also
map_shared() to open a shared region by name.
Examples
x <- share(rnorm(100))
shared_name(x)