# memory-region API reference

> The `memory_region` package, from memory-region 0.1.1, as published on mojoshelf (commit 40068c4f95ea), by `mojo doc` from Mojo 1.2.0.

## Modules

- [memory_region.bump](https://magmalake.dev/s/memory-region/api/bump.md): A cursor that only moves forward.
- [memory_region.ffi](https://magmalake.dev/s/memory-region/api/ffi.md): POSIX, for the two backings that need it.
- [memory_region.region](https://magmalake.dev/s/memory-region/api/region.md): Where a region's bytes come from, and what giving them back means.

Bytes that survive being moved.

A **region** is a contiguous byte range, however it was obtained: an ordinary
allocation, or a file mapped `MAP_SHARED` that another process can map by
name. A `BumpAllocator` carves one up.

The rule that makes it a library rather than a helper is that `claim` returns
an **offset**, not an address. A shared mapping lands somewhere different in
every process that maps it, so anything built inside a region has to refer to
itself by offset; a reader adds its own `base()` and it all resolves. What
that buys is a structure you can hand to someone else — through a file, a
shared mapping, an object store — without serialising it.

    var bump = BumpAllocator[MappedRegion](MappedRegion("/tmp/batch", size))
    var header = bump.claim(8)
    var payload = bump.append(some_bytes)
    bump.unsafe_ptr(header).unsafe_bitcast[Int64]()[unsafe_offset=0] = Int64(payload)
    bump^.close()          # unmaps; the file stays

and on the other side:

    var mapped = SharedMapping("/tmp/batch")   # read-only, unmapped at end of scope
    var head = mapped.span[DType.int64](header, 1)[0]
    var values = mapped.span[DType.uint8](Int(head), n)

## Dropping is safe, giving away is explicit

A region frees or unmaps itself at end of scope, because a leaked mapping has
no other symptom. `into_raw()` is how an export says the bytes are the
consumer's now: it consumes the region so the destructor does not run.

## What it does not do

**Grow.** A fixed range, so `claim` raises rather than reallocating. Size it
up front: a producer that knows its total sizes it exactly, one that does not
can over-allocate a mapping, since untouched pages never materialise.

**Free a piece.** The whole region goes at once.

**Describe itself.** A reader needs a manifest, and what that looks like
belongs to whoever owns the payload.