sharedbox 0.4.1__tar.gz → 0.6.0__tar.gz

{sharedbox-0.4.1 → sharedbox-0.6.0}/.github/dependabot.yml

@@ -4,6 +4,7 @@ updates:
     directory: /
     schedule:
       interval: weekly
+    labels: [dependencies, skip-changelog]
     commit-message:
       prefix: ci
     groups:
@@ -14,6 +15,7 @@ updates:
     directory: /
     schedule:
       interval: weekly
+    labels: [dependencies, skip-changelog]
     commit-message:
       prefix: build
       include: scope

sharedbox-0.6.0/.github/pull_request_template.md

@@ -0,0 +1,3 @@
+<!-- One bullet per change a reviewer can see, in the imperative. -->
+
+- [ ] Added a file to `changelog.d/` for each change a user notices, or this pull request changes nothing a user notices and needs the `skip-changelog` label

sharedbox-0.6.0/.github/workflows/check-changelog.yaml

@@ -0,0 +1,47 @@
+name: Changelog
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, labeled, unlabeled]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  entry:
+    name: Require a changelog entry
+    runs-on: ubuntu-latest
+    steps:
+      - name: Read the labels
+        id: labels
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          # read now rather than from the event: a pull request opened with a
+          # label gets it a moment after its "opened" event fires
+          skip=$(gh pr view "$PR" --repo "$REPO" --json labels --jq 'any(.labels[]; .name == "skip-changelog")')
+          echo "skip=$skip" >> "$GITHUB_OUTPUT"
+          if [ "$skip" = "true" ]; then
+            echo "Labelled skip-changelog: no entry needed."
+          fi
+
+      - uses: actions/checkout@v7
+        if: steps.labels.outputs.skip != 'true'
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        if: steps.labels.outputs.skip != 'true'
+        uses: astral-sh/setup-uv@v7
+
+      - name: Check for an entry in changelog.d
+        if: steps.labels.outputs.skip != 'true'
+        run: |
+          uvx towncrier==26.9.0 check --compare-with "origin/${{ github.base_ref }}" || {
+            echo "Add a file to changelog.d/ for each change, or ask for the skip-changelog label:"
+            echo "https://jacopoabramo.github.io/sharedbox/how-to/commits-and-prs/#changelog-entries"
+            exit 1
+          }

{sharedbox-0.4.1 → sharedbox-0.6.0}/.github/workflows/ci.yaml

@@ -19,7 +19,7 @@ jobs:
       # local hooks in prek.toml call `uv run --locked --only-group lint ...`
       - uses: astral-sh/setup-uv@v7
 
-      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0
+      - uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
         with:
           prek-version: "0.5.3"
 
@@ -88,7 +88,7 @@ jobs:
       - name: Create a box larger than a 16 MiB /dev/shm
         if: runner.os == 'Linux' && matrix.build == 'Release'
         run: |
-          docker run --rm --shm-size=16m -v "$PWD":/src -w /src ubuntu:24.04 build-cpp/test_small_shm
+          sudo unshare --mount sh -c 'mount -t tmpfs -o size=16m tmpfs /dev/shm && build-cpp/test_small_shm'
 
   build_wheels:
     name: Build wheel for ${{ matrix.python }}-${{ matrix.platform_id }}
@@ -114,7 +114,7 @@ jobs:
           ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v4.2.1
+        uses: pypa/cibuildwheel@v4.3.2
         env:
           CIBW_BUILD: ${{ matrix.python }}-${{ matrix.platform_id }}
           CIBW_CONTAINER_ENGINE: "docker; create_args: --shm-size=1g"
@@ -248,6 +248,14 @@ jobs:
           fetch-depth: 0
           ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
 
+      - name: Check the changelog has a section for a final release
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            python3 scripts/release_notes.py extract "${TAG#v}" > /dev/null
+          fi
+
       - name: Build SDist
         run: pipx run build --sdist
 
@@ -280,3 +288,25 @@ jobs:
           merge-multiple: true
 
       - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # final releases only: a release candidate's entries stay in changelog.d
+  # for the final release's section
+  github_release:
+    name: Write the GitHub release notes
+    needs: [upload_pypi]
+    if: github.event_name == 'release' && !github.event.release.prerelease
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Write the release's notes from its changelog section
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python3 scripts/release_notes.py extract "${TAG#v}" > notes.md
+          gh release edit "$TAG" --title "$TAG" --notes-file notes.md

sharedbox-0.6.0/.github/workflows/contention.yaml

@@ -0,0 +1,45 @@
+name: Contention
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - include/sharedbox/**
+      - src/sharedbox/_native/**
+      - src/sharedbox/benchmarks/contention.py
+      - .github/workflows/contention.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  contention:
+    name: Contention on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, windows-latest ]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install the project
+        run: uv sync --frozen --python 3.12
+
+      - name: Run benchbox contention
+        shell: bash
+        run: |
+          cores=$(uv run --no-sync python -c "import os; print(os.cpu_count())")
+          echo "### Contention on ${{ matrix.os }}, $cores logical cores" >> "$GITHUB_STEP_SUMMARY"
+          uv run --no-sync benchbox contention --json contention.json --markdown >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: contention-${{ matrix.os }}
+          path: contention.json

sharedbox-0.6.0/.github/workflows/ops.yaml

@@ -0,0 +1,90 @@
+name: Ops
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - include/sharedbox/**
+      - src/sharedbox/_native/**
+      - src/sharedbox/benchmarks/ops.py
+      - .github/workflows/ops.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ops:
+    name: Reads and writes against the base branch on Windows
+    runs-on: windows-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: head
+          fetch-depth: 0
+
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.base_ref || 'main' }}
+          path: base
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install both
+        shell: bash
+        run: |
+          for side in base head; do
+            (cd "$side" && uv sync --frozen --python 3.11)
+          done
+
+      - name: Run benchbox ops, alternating base and head
+        shell: bash
+        run: |
+          mkdir results
+          for round in 1 2 3; do
+            for side in base head; do
+              for rows in int record; do
+                (cd "$side" && uv run --no-sync benchbox ops --fast \
+                  --filter "*$rows/SharedBox" --json "../results/$side-$round-$rows.json")
+              done
+            done
+          done
+
+      - name: Compare the medians
+        shell: bash
+        run: |
+          cd head
+          uv run --no-sync python - ../results <<'EOF' | tee -a "$GITHUB_STEP_SUMMARY"
+          import statistics
+          import sys
+          from pathlib import Path
+
+          import pyperf
+          from sharedbox.benchmarks._app import machine
+
+          means: dict[tuple[str, str], list[float]] = {}
+          for path in sorted(Path(sys.argv[1]).glob("*.json")):
+              side = path.name.split("-")[0]
+              for bench in pyperf.BenchmarkSuite.load(str(path)).get_benchmarks():
+                  means.setdefault((bench.get_name(), side), []).append(bench.mean())
+          print("### benchbox ops on Windows cp311, median of three rounds")
+          print()
+          print(machine())
+          print()
+          print("| benchmark | base | head | head / base |")
+          print("| --- | --- | --- | --- |")
+          for name in sorted({name for name, _ in means}):
+              base = statistics.median(means.get((name, "base"), [0.0]))
+              head = statistics.median(means.get((name, "head"), [0.0]))
+              # A row added or removed by the pull request has times on one side only.
+              cells = [f"{v * 1e9:.1f} ns" if v else "-" for v in (base, head)]
+              ratio = f"{head / base:.3f}" if base and head else "-"
+              print(f"| {name} | {cells[0]} | {cells[1]} | {ratio} |")
+          EOF
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ops
+          path: results

sharedbox-0.6.0/.github/workflows/prepare-release.yaml

@@ -0,0 +1,78 @@
+name: Prepare release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release, such as 0.6.0, without the v"
+        required: true
+        type: string
+      dry_run:
+        description: "Only show the changelog section, in the run's summary"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    name: Write the changelog section and open the release pull request
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the version
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "The version must look like 0.6.0, without the v; got '$VERSION'."
+            echo "Tag a release candidate instead of preparing it."
+            exit 1
+          fi
+
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+
+      - name: Check there is something to release
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          # towncrier refuses a version only when the whole heading matches,
+          # date included, so on a later day it would write a second section
+          if python3 scripts/release_notes.py extract "$VERSION" > /dev/null 2>&1; then
+            echo "The changelog already has a section for $VERSION."
+            exit 1
+          fi
+          if [ -z "$(find changelog.d -type f ! -name .gitkeep)" ]; then
+            echo "changelog.d holds no entries, so there is nothing to release."
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Write the section
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          uvx towncrier==26.9.0 build --yes --version "$VERSION" --date "$(date -u +%d-%m-%Y)"
+          python3 scripts/release_notes.py extract "$VERSION" > notes.md
+          cat notes.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Open the release pull request
+        if: ${{ !inputs.dry_run }}
+        env:
+          VERSION: ${{ inputs.version }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          branch="release/v$VERSION"
+          git switch -c "$branch"
+          git commit -m "docs: write the $VERSION changelog"
+          git push origin "$branch"
+          gh pr create --base main --head "$branch" --label skip-changelog \
+            --title "docs: write the $VERSION changelog" --body-file notes.md

sharedbox-0.6.0/.github/workflows/streams.yaml

@@ -0,0 +1,85 @@
+name: Streams
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - include/sharedbox/stream.hpp
+      - include/sharedbox/core.hpp
+      - src/sharedbox/_stream.py
+      - src/sharedbox/_native/stream.cpp
+      - src/sharedbox/_native/types.cpp
+      - src/sharedbox/_native/codec.cpp
+      - src/sharedbox/benchmarks/stream.py
+      - scripts/stream_compare.py
+      - .github/workflows/streams.yaml
+  workflow_dispatch:
+    inputs:
+      base:
+        description: Commit, branch or tag to compare against
+        required: false
+        default: main
+
+permissions:
+  contents: read
+
+jobs:
+  streams:
+    name: Streams against the base on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, windows-latest ]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: head
+          fetch-depth: 0
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.base || github.base_ref || 'main' }}
+          path: base
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+      - name: Install both
+        shell: bash
+        run: |
+          for side in base head; do
+            (cd "$side" && uv sync --frozen --python 3.12)
+          done
+      - name: Check the base has SharedStream
+        id: base
+        shell: bash
+        run: |
+          if (cd base && uv run --no-sync python -c "import sharedbox; sharedbox.SharedStream"); then
+            echo "sides=base head" >> "$GITHUB_OUTPUT"
+          else
+            echo "sides=head" >> "$GITHUB_OUTPUT"
+            echo "base has no SharedStream; head only" | tee -a "$GITHUB_STEP_SUMMARY"
+          fi
+      - name: Run the stream benchmarks, alternating
+        shell: bash
+        run: |
+          mkdir results
+          for round in 1 2 3; do
+            if [ "${{ steps.base.outputs.sides }}" != "head" ]; then
+              (cd base && uv run --no-sync python ../head/src/sharedbox/benchmarks/stream.py \
+                --short --table both --json "../results/base-$round.json") \
+                || echo "::warning::base round $round failed"
+            fi
+            (cd head && uv run --no-sync python ../head/src/sharedbox/benchmarks/stream.py \
+              --short --table both --json "../results/head-$round.json")
+          done
+      - name: Compare
+        if: ${{ !cancelled() }}
+        shell: bash
+        run: |
+          cd head
+          uv run --no-sync python ../head/scripts/stream_compare.py ../results | tee -a "$GITHUB_STEP_SUMMARY"
+      - uses: actions/upload-artifact@v7
+        if: ${{ !cancelled() }}
+        with:
+          name: streams-${{ matrix.os }}
+          path: results

{sharedbox-0.4.1 → sharedbox-0.6.0}/.gitignore

@@ -20,9 +20,10 @@ wheelhouse/
 
 graphify-out/
 
-build-cpp/
+build-cpp*/
 
 .hypothesis/
+.claude/settings.json
 .claude/settings.local.json
 
 site/

{sharedbox-0.4.1 → sharedbox-0.6.0}/CHANGELOG.md

@@ -7,7 +7,177 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Dates are marked as `DD-MM-YYYY`
 
-## [Unreleased]
+<!-- towncrier release notes start -->
+
+## [0.6.0](https://github.com/jacopoabramo/sharedbox/releases/tag/v0.6.0) - 24-10-2026
+
+### Added
+
+- `status::foreign` and `SBX_E_FOREIGN` (-12): the segment's magic is not
+  one this version knows. Python raises `SchemaMismatchError`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::to_expected` and `sharedbox::from_expected`: convert a
+  `sharedbox::result` to a `std::expected` and back on C++23. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `KindMismatchError`, a `SchemaMismatchError` raised when a name holds a
+  segment of another kind; `status::kind_mismatch` and `SBX_E_KIND` (-11)
+  in `sharedbox.hpp` and `sharedbox_c.h`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::stream`, `sharedbox::stream_sender` and `sharedbox::stream_reader`
+  in `stream.hpp`, included by `sharedbox.hpp`: a ring in shared memory with
+  one sender and up to `max_readers` readers, each reading
+  `read_mode::lossless`, `read_mode::lossy` or `read_mode::latest`, laid out
+  as stream layout 1.0. C++ only. `stream_sender::begin`, `publish` and
+  `abandon` reserve a slot, fill it in place and publish it or give it up. ([#48](https://github.com/jacopoabramo/sharedbox/pull/48))
+- `status::busy` (-13), `status::ended` (-14) and `status::interrupted`
+  (-15), with `SBX_E_BUSY`, `SBX_E_ENDED` and `SBX_E_INTERRUPTED` in
+  `sharedbox_c.h`. ([#48](https://github.com/jacopoabramo/sharedbox/pull/48))
+- `SharedStream`, `SharedSendStream` and `SharedReceiveStream`: send items of
+  any type a `SharedBox` field takes from one process to up to `max_readers`
+  readers, each reading `lossless`, `lossy` or `latest`, with blocking,
+  non-blocking and asyncio calls, `receive_into` into the caller's arrays and
+  `receive_future`, a `concurrent.futures.Future`. A stream passed to another
+  process arrives attached, or raises `SchemaMismatchError` if its name now
+  holds a stream created since, and `SharedStream.create` without a name gives
+  the stream a new one. The ends cannot be pickled; `SharedSendStream.stream`
+  and `SharedReceiveStream.stream` return their stream. ([#49](https://github.com/jacopoabramo/sharedbox/pull/49))
+- `SharedReceiveStream.events`, a `ReceiveEvents` psygnal group whose
+  `received` and `ended` signals deliver a reader's items to callbacks. ([#49](https://github.com/jacopoabramo/sharedbox/pull/49))
+- `WouldBlock`, `EndOfStream`, `StreamBusyError` and `StreamClosedError`. ([#49](https://github.com/jacopoabramo/sharedbox/pull/49))
+- `SharedStreamStatistics` and `ReceiveStreamStatistics`, returned by
+  `SharedStream.statistics()`. ([#49](https://github.com/jacopoabramo/sharedbox/pull/49))
+- `WaiterSlotsFullError` is exported from `sharedbox`; opening a reader
+  raises it when `max_readers` readers are open. ([#49](https://github.com/jacopoabramo/sharedbox/pull/49))
+- `benchbox ops`: the row `watched write int`, a write while another process
+  has a watcher open. ([#50](https://github.com/jacopoabramo/sharedbox/pull/50))
+- `sharedbox::handle::sleepers()`: the number of threads inside a wait on
+  the box, in any process. ([#51](https://github.com/jacopoabramo/sharedbox/pull/51))
+- `benchbox stream`: items per second of `SharedStream` readers in each mode
+  against `mp.Queue` and a `SharedMemory` ring with a lock, and a table of
+  `send` and `asend` with `receive`, `async for` and `events.received`,
+  with the 50th, 90th and 99th percentile latency. `--short`, `--table`,
+  `--json` and `--markdown` are its options; `benchbox all` runs it and
+  writes `stream.json`. ([#53](https://github.com/jacopoabramo/sharedbox/pull/53))
+- `Streams` workflow: `benchbox stream` on the base branch against the pull
+  request, with `scripts/stream_compare.py` writing the table. ([#53](https://github.com/jacopoabramo/sharedbox/pull/53))
+- `benchbox roundtrip`: the row `SharedStream`. ([#53](https://github.com/jacopoabramo/sharedbox/pull/53))
+- `benchmarks/test_bench_stream.py`: a CodSpeed benchmark of `send` plus
+  `receive_into`. ([#53](https://github.com/jacopoabramo/sharedbox/pull/53))
+- `FieldWatch.future()`, returning a `FieldFuture`, a
+  `concurrent.futures.Future` of the next write to the field; `FieldFuture`
+  is exported from `sharedbox`. ([#55](https://github.com/jacopoabramo/sharedbox/pull/55))
+- `field(shape=...)`: the sizes of an array field of a box.
+
+  ```python
+  class Grid(SharedBox):
+      cells: npt.NDArray[np.uint8] = np.zeros((4, 6), np.uint8)
+      weights: npt.NDArray[np.float32] = field(shape=(3,))
+  ```
+
+  A box array field also takes its sizes from a plain default array, so it
+  needs no `Shape` and, with a dtype in its annotation, no `DType`. ([#56](https://github.com/jacopoabramo/sharedbox/pull/56))
+- `SharedSendStream.writing()` and `SharedSendStream.awriting()`, which yield a
+  `SendSlot`:
+
+  ```python
+  blank = Frame(0, np.empty((0, 0), np.uint16))
+  with sender.writing(blank) as slot:
+      slot.item.image.fill(0)
+      slot.send(replace(slot.item, index=1))
+  ```
+
+  `slot.item` is an item built from a template, with arrays over the next slot
+  to fill in place, and `slot.send(item)` publishes an item without copying the
+  arrays already in the slot. ([#58](https://github.com/jacopoabramo/sharedbox/pull/58))
+
+### Changed
+
+- `sharedbox.hpp`: split into `core.hpp` and `box.hpp`, which it includes.
+  `sharedbox::result` is the library's own type on C++20 and C++23 alike,
+  and its `error()` is a `sharedbox::error` holding the status, the OS error
+  and what was found. The C++ names moved from `sharedbox::v2` to
+  `sharedbox::v3`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::header`: the magic, versions, schema hash, creator, waiter
+  slot count and size moved into its first member, `common`, a
+  `sharedbox::common_header`; `layout_major` and `layout_minor` became
+  `common.kind_major` and `common.kind_minor`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::error`: a `status::os` failure carries the OS error in
+  `error().os`; `errno` and `GetLastError()` no longer hold it reliably
+  when the call returns. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- Segment layout: every segment starts with a common first line (magic,
+  core version, layout version of its kind, schema hash, creator), and
+  boxes use layout 3.0. A box made by 0.5 cannot be opened by 0.6, nor the
+  other way round. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::inspect`: returns `result<common_header>`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::magic`: renamed `sharedbox::box_magic`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `box_ref`: a reference field stores the name of its target in 240 bytes,
+  so the field takes 256 bytes. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `SharedBox` names: one or more segments of `[A-Za-z0-9_-]` joined by
+  `:`, up to 240 characters, such as `bl01:camera:det1:frames`. `.` is no
+  longer allowed. The shared memory is `/dev/shm/SBX:<name>` on Linux and
+  `Local\SBX:<name>` on Windows, and Windows waiter events end in `#w<i>`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `SharedBox.attach`: a segment whose magic this version does not know,
+  such as a box made by 0.5, raises `SchemaMismatchError` at once, instead
+  of `SegmentNotFoundError` after the timeout. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `SharedBox` write: makes a wake call only when a thread is waiting on the
+  box. `sleepers`, at offset 84 of box layout 3.0, counts the threads inside
+  a wait. It adds 1 to `wake_word` only when `sleepers` is not 0. ([#51](https://github.com/jacopoabramo/sharedbox/pull/51))
+- `sharedbox::waiter_slot`: 32 bytes, with `asleep_on`, at offset 24, the
+  offset of the count the slot's current wait added 1 to, and a reserved
+  word. Freeing the slot of a process killed inside a wait takes that
+  thread out of `sleepers` for a box, and out of `data_waiting` or
+  `space_waiting` for a stream. ([#51](https://github.com/jacopoabramo/sharedbox/pull/51))
+- `benchbox plot`: writes plotly figure JSON (`charts/ops.json`,
+  `roundtrip.json`, `stream-throughput.json`, `stream-matrix.json`) instead
+  of SVG files. ([#53](https://github.com/jacopoabramo/sharedbox/pull/53))
+- `benchmarks` extra and group: depend on `plotly` instead of `matplotlib`. ([#53](https://github.com/jacopoabramo/sharedbox/pull/53))
+- Array fields: an annotation that names its number of dimensions, as in
+  `numpy.ndarray[tuple[int, int], numpy.dtype[numpy.uint8]]`, raises
+  `TypeError` when its `Shape` has another number, in a box, a record and a
+  stream item. ([#56](https://github.com/jacopoabramo/sharedbox/pull/56))
+- Array fields: a default array whose shape differs from the field's `Shape`
+  raises `TypeError` instead of `ValueError` when the class is defined. ([#56](https://github.com/jacopoabramo/sharedbox/pull/56))
+
+### Removed
+
+- Reading box layouts 1.0 and 2.0. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+- `sharedbox::oldest_layout_major`. ([#47](https://github.com/jacopoabramo/sharedbox/pull/47))
+
+
+## [0.5.0] - 09-10-2026
+
+### Added
+
+- `SharedBox.read_into`: copies an array field into an array the caller
+  passes and returns it, without allocating a new array.
+- `SharedBox.writing`: a context manager that holds the box's write lock
+  and yields an array field as an array to fill in place.
+- `benchbox contention`: times writes and reads of an `int` while several
+  writer and reader processes share it, for a box, `mp.Value` and
+  `SharedMemory` with a `Lock`.
+
+### Changed
+
+- `SharedBox`: a field named `read_into` raises `TypeError`.
+- `SharedBox`: a field named `writing` raises `TypeError`.
+- `SharedBox`: reading a collection, tuple or record field whose members
+  are `bool`, `int`, `float` or `str` takes less time: about 90 ns less
+  for a list of 16 `float` on Windows.
+- `SharedBox`: reading a field whose value cannot be changed (a frozen
+  dataclass, attrs class or msgspec Struct, a NamedTuple, a tuple, a
+  frozenset, an enum, flag or literal, `complex`, `date`, `time`,
+  `datetime`, `timedelta`, `UUID` or `Decimal`) returns the value the
+  previous read built until the field is written: 40 ns instead of 540 ns
+  for a frozen dataclass of four fields on Windows. A tuple, frozenset or
+  record qualifies only when its members are of these kinds or `bool`,
+  `int`, `float`, `str` or `bytes`.
+- `SharedBox`: a frozen record's `__post_init__`, attrs converters and
+  validators run on the first read after each write instead of on every
+  read.
+
+### Fixed
+
+- `SharedBox.attach`: a box whose header gives a field count other than the
+  class's raises `SchemaMismatchError` instead of `ValueError`.
+
+## [0.4.1] - 07-10-2026
 
 ### Changed
 
@@ -292,7 +462,8 @@ stage.events.nested.connect(lambda path, new, old: print(path, new))
 
 - Initial release
 
-[Unreleased]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.0...HEAD
+[0.5.0]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/jacopoabramo/sharedbox/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/jacopoabramo/sharedbox/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/jacopoabramo/sharedbox/compare/0.2.4...v0.3.0