---
title: "Introduction to mizu"
format:
  html:
    toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to mizu}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

mizu provides parallel computation and data exchange between R processes on the same machine: lock-free channels and work-stealing task pools over POSIX shared memory (Linux, macOS) or Win32 file mappings (Windows).

A channel is a two-way message link between an R session and a helper process that it spawns.
A pool is a set of worker processes that divide submitted tasks among themselves.

In both, one process writes data into shared memory and the other reads it in place, with no copy through a socket, pipe, or file.

``` r
library(mizu)

p <- mizu_pool(n_workers = 4L)
t <- mizu_submit(p, sum(x) + y, x = 1:10, y = 100)
mizu_collect(t)
#> [1] 155
m <- mizu_map(p, 1:5, \(i) i * 2L, .template = integer(1))
mizu_collect(m)
#> [1]  2  4  6  8 10
mizu_pool_stop(p)
```

## The articles

- [Benchmarks](benchmarks.html) — measurements against mirai.
- [Channels](channels.html) — two-way message links between R processes: send and receive, batched forms, sentinel values, remote errors.
- [Task pools](pools.html) — work-stealing worker pools: submit and collect, nested tasks, waiting on several tasks, sizing and observing a pool.
- [Parallel map](map.html) — `mizu_map()`: mapping over a pool with the function and data staged once, templates, reproducible random numbers, prepared maps.
- [Python interop](interop.html) — channels and pools shared with Python processes through pymizu, including the cross-language map.
- [Operations](operations.html) — sizing `/dev/shm` on Linux, the Linux memory allocator, and what happens when a process crashes.