% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/share.R
\name{share}
\alias{share}
\title{Zero-Copy Shared Objects}
\usage{
share(
  x,
  backing = c("auto", "mmap", "shm"),
  readonly = TRUE,
  name = NULL,
  deep = FALSE,
  min_bytes = 64 * 1024 * 1024,
  cycle = c("error", "skip"),
  mode = c("balanced", "strict")
)
}
\arguments{
\item{x}{An R object to share. Supports vectors, matrices, arrays, lists,
data frames, and any object that can be serialized with \code{serialize()}.}

\item{backing}{Backing type: "auto" (default), "mmap", or "shm".
\itemize{
\item \code{"auto"}: Let the system choose the best option.
\item \code{"mmap"}: File-backed memory mapping. Most portable.
\item \code{"shm"}: POSIX shared memory or Windows named mapping.
}}

\item{readonly}{Logical. If TRUE (default), the segment is protected after
writing, making it read-only. Set to FALSE only if you need to modify
the shared data (advanced use case).}

\item{name}{Optional name for the shared object. If NULL (default), a unique
name is generated. Named shares can be opened by name in other processes.}

\item{deep}{Logical. If TRUE, recursively traverse lists and data.frames,
sharing individual components that meet the size threshold. When FALSE
(default), the entire object is serialized as one unit.}

\item{min_bytes}{Minimum size in bytes for an object to be shared when
deep=TRUE. Objects smaller than this threshold are kept in-place.
Default is 64MB (64 * 1024 * 1024).}

\item{cycle}{How to handle cyclic references when deep=TRUE. Either "error"
(default) to stop with an error, or "skip" to skip cyclic references.}

\item{mode}{Sharing mode when deep=TRUE. Either "balanced" (default) to
continue on hook errors and non-shareable types, or "strict" to error.}
}
\value{
A \code{shard_shared} object (when deep=FALSE) or
\code{shard_deep_shared} object (when deep=TRUE) containing:
\itemize{
\item \code{path}: The path or name of the shared segment
\item \code{backing}: The backing type used
\item \code{size}: Total size in bytes
\item \code{readonly}: Whether the segment is protected
\item \code{class_info}: Original class information
}
}
\description{
Create shared memory representations of R objects for efficient
parallel access without duplication.

Creates a shared memory representation of an R object. The object is
serialized once and can be accessed by multiple worker processes without
copying.
}
\details{
The \code{share()} function is the primary high-level API for creating zero-copy
shared inputs. When you share an object:

\enumerate{
\item The object is serialized into a shared memory segment
\item The segment is marked read-only (protected)
\item A lightweight handle is returned that can be passed to workers
\item Workers attach to the segment and deserialize on demand
}

This approach eliminates per-worker duplication of large inputs. The data
exists once in shared memory, and all workers read from the same location.

\strong{Immutability Contract}: Shared objects are immutable by design.
Any attempt to modify shared data in a worker will fail. This guarantees
deterministic behavior and prevents accidental copy-on-write.
}
\examples{
\donttest{
mat <- matrix(rnorm(1e4), nrow = 100)
shared_mat <- share(mat)
recovered <- fetch(shared_mat)
identical(mat, recovered)
close(shared_mat)
}
}
\seealso{
\code{\link{segment_create}} for low-level segment operations,
\code{\link{pool_create}} for worker pool management.
}
