% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arena.R
\name{arena}
\alias{arena}
\title{Arena Semantic Scope}
\usage{
arena(
  expr,
  strict = FALSE,
  escape_threshold = .arena_escape_threshold,
  gc_after = strict,
  diagnostics = FALSE
)
}
\arguments{
\item{expr}{An expression to evaluate within the arena scope.}

\item{strict}{Logical. If TRUE, enables strict mode which:
\itemize{
\item Warns if large objects (> 1MB by default) escape the scope
\item Triggers garbage collection after scope exit
\item Tracks memory growth for diagnostics
}
Default is FALSE for compatibility and performance.}

\item{escape_threshold}{Numeric. Size in bytes above which returned objects
trigger a warning in strict mode. Default is 1MB (1048576 bytes).
Only used when \code{strict = TRUE}.}

\item{gc_after}{Logical. If TRUE, triggers garbage collection after the
arena scope exits. Default is TRUE in strict mode, FALSE otherwise.}

\item{diagnostics}{Logical. If TRUE, returns diagnostics about memory usage
along with the result. Default is FALSE.}
}
\value{
The result of evaluating \code{expr}. If \code{diagnostics = TRUE},
returns an \code{arena_result} object with elements \code{result} and
\code{diagnostics}.
}
\description{
Semantic scope for scratch memory that signals temporary data
should not accumulate. Enables memory-conscious parallel execution.

Evaluates an expression in a semantic scope that signals scratch memory usage.
This enables memory-conscious execution where temporaries are expected to be
reclaimed after the scope exits.
}
\details{
The \code{arena()} function provides a semantic scope that signals "this code
produces scratch data that should not outlive the scope." It serves two
purposes:

\enumerate{
\item \strong{For compiled kernels}: When Rust-based kernels are available,
arena() provides real scratch arenas backed by temporary shared memory
segments that are automatically reclaimed.
\item \strong{For arbitrary R code}: Triggers post-task memory checks to
detect growth and potential memory leaks.
}

The \code{strict} parameter controls escape detection:
\itemize{
\item \code{strict = FALSE} (default): Returns results normally, logs
diagnostics about memory growth.
\item \code{strict = TRUE}: Warns or errors if large objects escape the
scope, and triggers aggressive memory reclamation.
}
}
\examples{
\donttest{
result <- arena({
  tmp <- matrix(rnorm(1e6), nrow = 1000)
  colMeans(tmp)
})

info <- arena({
  x <- rnorm(1e5)
  sum(x)
}, diagnostics = TRUE)
info$diagnostics
}
}
\seealso{
\code{\link{shard_map}} for parallel execution,
\code{\link{share}} for shared memory inputs.
}
