% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/shard_reduce.R
\name{shard_reduce}
\alias{shard_reduce}
\title{Streaming Reductions over Shards}
\usage{
shard_reduce(
  shards,
  map,
  combine,
  init,
  borrow = list(),
  out = list(),
  workers = NULL,
  chunk_size = 1L,
  profile = c("default", "memory", "speed"),
  mem_cap = "2GB",
  recycle = TRUE,
  cow = c("deny", "audit", "allow"),
  seed = NULL,
  diagnostics = TRUE,
  packages = NULL,
  init_expr = NULL,
  timeout = 3600,
  max_retries = 3L,
  health_check_interval = 10L
)
}
\arguments{
\item{shards}{A \code{shard_descriptor} from \code{\link[=shards]{shards()}}, or an integer N.}

\item{map}{Function executed per shard. Receives shard descriptor as first
argument, followed by borrowed inputs and outputs.}

\item{combine}{Function \verb{(acc, value) -> acc} used to combine results. Should
be associative for deterministic behavior under chunking.}

\item{init}{Initial accumulator value.}

\item{borrow}{Named list of shared inputs (same semantics as \code{\link[=shard_map]{shard_map()}}).}

\item{out}{Named list of output buffers/sinks (same semantics as \code{\link[=shard_map]{shard_map()}}).}

\item{workers}{Number of worker processes.}

\item{chunk_size}{Shards to batch per worker dispatch (default 1).}

\item{profile}{Execution profile (same semantics as \code{\link[=shard_map]{shard_map()}}).}

\item{mem_cap}{Memory cap per worker (same semantics as \code{\link[=shard_map]{shard_map()}}).}

\item{recycle}{Worker recycling policy (same semantics as \code{\link[=shard_map]{shard_map()}}).}

\item{cow}{Copy-on-write policy for borrowed inputs (same semantics as \code{\link[=shard_map]{shard_map()}}).}

\item{seed}{RNG seed for reproducibility.}

\item{diagnostics}{Logical; collect diagnostics (default TRUE).}

\item{packages}{Additional packages to load in workers.}

\item{init_expr}{Expression to evaluate in each worker on startup.}

\item{timeout}{Seconds to wait for each chunk.}

\item{max_retries}{Maximum retries per chunk.}

\item{health_check_interval}{Check worker health every N completions.}
}
\value{
A \code{shard_reduce_result} with fields:
\itemize{
\item \code{value}: final accumulator
\item \code{failures}: any permanently failed chunks
\item \code{diagnostics}: run telemetry including reduction stats
\item \code{queue_status}, \code{pool_stats}
}
}
\description{
Reduce shard results without gathering all per-shard returns on the master.

\code{shard_reduce()} executes \code{map()} over shards in parallel and combines results
using an associative \code{combine()} function. Unlike \code{shard_map()}, it does not
accumulate all per-shard results on the master; it streams partials as chunks
complete.
}
\details{
For performance and memory efficiency, reduction is performed in two stages:
\enumerate{
\item per-chunk partial reduction inside each worker, and
\item streaming combine of partials on the master.
}
}
\examples{
\donttest{
res <- shard_reduce(
  100L,
  map = function(s) sum(s$idx),
  combine = function(acc, x) acc + x,
  init = 0,
  workers = 2
)
pool_stop()
res$value
}
}
