sharedbox 0.8.0__tar.gz → 0.9.0__tar.gz

{sharedbox-0.8.0 → sharedbox-0.9.0}/.github/workflows/ci.yaml

@@ -114,7 +114,7 @@ jobs:
           ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v4.3.4
+        uses: pypa/cibuildwheel@v4.3.5
         env:
           CIBW_BUILD: ${{ matrix.python }}-${{ matrix.platform_id }}
           CIBW_CONTAINER_ENGINE: "docker; create_args: --shm-size=1g"

{sharedbox-0.8.0 → sharedbox-0.9.0}/CHANGELOG.md

@@ -9,6 +9,63 @@ Dates are marked as `DD-MM-YYYY`
 
 <!-- towncrier release notes start -->
 
+## [0.9.0](https://github.com/jacopoabramo/sharedbox/releases/tag/v0.9.0) - 04-11-2026
+
+### Added
+
+- `segment_status`: `segment_status("lab:counts")` returns a `SegmentStatus`,
+  `missing` when no box or stream is published under the name, `running` while the
+  process that created it runs and `creator_exited` once it has ended.
+  `core.hpp` adds `segment_status` and `segment_state` for C++. ([#94](https://github.com/jacopoabramo/sharedbox/pull/94))
+- `SharedReceiveStream.fetch`, `fetch_into` and `fetch_future`: `reader.fetch(120)`
+  returns the item at position 120, waiting until the sender has sent it, and
+  leaves the reader's receive cursor and `missed` unchanged. `ItemGoneError`, a
+  `LookupError` whose `oldest` is the oldest position the ring held, is raised
+  once the ring no longer holds the item. `stream.hpp` adds
+  `stream_reader::fetch` and `fetch_with` for C++. ([#95](https://github.com/jacopoabramo/sharedbox/pull/95))
+- `MaxShape` on box fields: a box field declared as
+  `Annotated[npt.NDArray[np.uint16], MaxShape((2048, 2048))]` holds an array of
+  any shape up to that maximum, as kind 75 of box layout 3.3, and every read
+  returns an array of the stored shape. A write stores the shape and only the
+  elements in use. `SharedBox.writing` takes `shape`, so
+  `box.writing("image", shape=(480, 640))` sets the shape and yields a view of
+  it under one lock. `read_into` raises `TypeError` for a `MaxShape` field. ([#97](https://github.com/jacopoabramo/sharedbox/pull/97))
+- `BoundedList`, `BoundedSet` and `BoundedDict` take their element types as the
+  first arguments when the class fixes none: `BoundedList(int, [1, 2], capacity=4)`
+  equals `BoundedList[int]([1, 2], capacity=4)`, and
+  `BoundedDict(str, float, {"a": 1.0}, capacity=8)` takes the key and value types. ([#97](https://github.com/jacopoabramo/sharedbox/pull/97))
+- `Timed` and `Timed.now`: a box field, record member, collection element or
+  stream item declared as `Timed[float]` stores the value with a timestamp in
+  nanoseconds since the Unix epoch, and `box.temperature = Timed.now(21.5)` stamps
+  it with the system clock when the write holds the box's lock, or just before a
+  stream send publishes the item. A `Timed` with a timestamp of its own is stored as
+  given. Timed values are kind 77, and streams use stream layout 1.5. ([#99](https://github.com/jacopoabramo/sharedbox/pull/99))
+- `Attr`, `attr`, `AttrValue`, `RequestFuture` and `RequestServer`: a box
+  field declared as `exposure: Attr[float] = attr(timed=True, settable=True)`
+  holds a value its owner writes with
+  `box.exposure.publish(value=..., setpoint=...)` and any process reads with
+  `.value`, `.setpoint`, `.timestamp_ns` or `read()`, or watches with
+  `watch` and `events`. An attribute with arguments, such as
+  `move: Attr[float, [float]] = attr()`, or a settable one carries a typed
+  request to the one process that serves it: `box.move.serve(handler)`
+  answers with a sync or async handler, and `box.move(5.0)` or
+  `box.exposure.set(0.02)` returns a `RequestFuture` waited on with
+  `.result(timeout)` or `await`. Of the requests sent while the handler
+  runs, only the newest is handled next. `RequestError`,
+  `RequestSupersededError` and `ServerExitedError` report a failed, replaced
+  or abandoned request, and `AlreadyServedError` a second server. Attribute
+  fields are kind 76 of box layout 3.3, and `box.hpp` adds `attr_publish`,
+  `attr_read`, `attr_published`, `attr_value_at` and the request protocol
+  steps on `handle` for C++, and `type_view` gives an attribute's flags and
+  where its value, timestamp and setpoint start. ([#103](https://github.com/jacopoabramo/sharedbox/pull/103))
+
+### Fixed
+
+- On Windows, an operating system failure to create or open a box or stream raises
+  `OSError` with the Windows error code in `winerror`, such as `PermissionError`
+  for a segment the process may not open, instead of `RuntimeError`. ([#96](https://github.com/jacopoabramo/sharedbox/pull/96))
+
+
 ## [0.8.0](https://github.com/jacopoabramo/sharedbox/releases/tag/v0.8.0) - 30-10-2026
 
 ### Breaking

{sharedbox-0.8.0 → sharedbox-0.9.0}/CLAUDE.md

@@ -14,8 +14,8 @@ the layout and the native module converts values.
 sharedbox/
 |-- include/sharedbox/
 |   |-- core.hpp               what every segment kind uses: result and error, liveness, names, mappings, the open step, waiter slots, the type codec, the metadata area and its CBOR check
-|   |-- box.hpp                box layout 3.2 and its protocols: create, publish, open, lock, read, write, metadata, capsule handle
-|   |-- stream.hpp             stream layout 1.4: create, open, the sender, readers, the gate, dead ends, metadata
+|   |-- box.hpp                box layout 3.3 and its protocols: create, publish, open, lock, read, write, metadata, capsule handle
+|   |-- stream.hpp             stream layout 1.5: create, open, the sender, readers, the gate, dead ends, metadata
 |   |-- sharedbox.hpp          includes every kind; the header consumers include
 |   |-- sharedbox_c.h          minimal C interface: sbx_open, sbx_import, sbx_read, sbx_write, sbx_schema_hash, sbx_release, sbx_field_desc, typed sbx_read_* and sbx_write_*, sbx_metadata_head, sbx_read_metadata, sbx_add_metadata
 |   `-- sharedbox_c.cpp        its implementation, compiled by the consumer (CMake target sharedbox::c)
@@ -26,15 +26,19 @@ sharedbox/
 |-- src/sharedbox/
 |   |-- __init__.py            re-exports the public API, get_include()
 |   |-- _box.py                SharedBox: class keywords, fields, fields(), create/attach, __post_init__, update, snapshot, unlink, __sharedbox_box__
-|   |-- _layout.py             Capacity, field() and Field, field offsets and kind codes, schema hash
+|   |-- _layout.py             Capacity, field(), attr() and Field, field offsets and kind codes, schema hash
 |   |-- _types.py              annotation parsing into TypeSpec, the description table
 |   |-- _arrays.py             Shape, MaxShape, DType, SupportsDLPack, register_array_type
-|   |-- _events.py             BoxEvents, FieldWatch, the watcher thread
+|   |-- _timed.py              Timed: a value with its timestamp in ns, Timed.now and the mark a write replaces
+|   |-- _attr.py               Attr and AttrValue: the handle of an attribute field, publish, read, requests and serve
+|   |-- _request.py            request fields: RequestFuture, RequestServer, the request errors, serving threads and tasks
+|   |-- _events.py             BoxEvents, FieldWatch, the watcher thread, which also completes request futures and kicks request servers
 |   |-- _follow.py             BoxEvents.follow and unfollow: forwarding the events of boxes that references reach
 |   |-- _stream.py             SharedStream, SharedSendStream, SharedReceiveStream, ReceiveEvents, the statistics classes, the worker threads
 |   |-- _metadata.py           metadata documents: the type variable M, CBOR encoding, read-only decoding, the cache of decoded versions
 |   |-- _refs.py               reference fields: BoxRef, the class registry, BrokenReferenceError, UnknownBoxClassError
-|   |-- _exit.py               the exit handler: stops the watcher and stream threads, closes boxes, streams and ends,
+|   |-- _status.py             segment_status and SegmentStatus: whether a name holds a segment and its creator runs
+|   |-- _exit.py               the exit handler: stops the watcher, request server and stream threads, closes boxes, streams and ends,
 |   |                          replaces the native objects of watchers and box classes
 |   |-- _native.pyi            hand-written stub for the extension
 |   |-- py.typed
@@ -71,12 +75,17 @@ sharedbox/
 |   |-- test_native_waiters.py waiter slots, dead owners, interrupt
 |   |-- test_box_sync_async.py a sync and an async watch on one box in two threads
 |   |-- test_metadata.py       metadata of a box: documents, versions, events, typed access, reserved names
+|   |-- test_segment_status.py segment_status: missing, running and an exited creator
 |   |-- test_stream.py         SharedStream, sender and reader, blocking and non-blocking calls
 |   |-- test_stream_metadata.py  metadata of a stream: the version of each item, in one process and across processes
 |   |-- test_stream_async.py   asyncio calls on a stream, cancellation
 |   |-- test_stream_events.py  ReceiveEvents delivery
+|   |-- test_stream_fetch.py   fetching an item by its position, in one process and across processes
 |   |-- test_stream_processes.py  streams across processes, dead senders and readers
 |   |-- test_stream_fork.py    stream ends inherited through fork
+|   |-- test_timed.py          Timed fields and stream items: stamps, given times, where a Timed may go
+|   |-- test_attr.py           attribute requests across processes: answers, superseding, a killed server, close, async handlers
+|   |-- test_attr_fields.py    Attr in the layout: publish, read, watch, refused operations, where an Attr may go
 |   |-- streamproc.py          helpers that run a stream end in another process
 |   |-- test_properties_*.py   Hypothesis property tests, streams included
 |   |-- stress/                stress tests, marker stress, deselected by default
@@ -96,7 +105,7 @@ sharedbox/
 |   |-- examples/              one script per how-to guide, included by the guide
 |   |-- javascripts/charts.js  draws each div of class sbx-chart from a plotly figure JSON file
 |   |-- assets/benchmarks/     the figure JSON files of the performance page, from benchbox plot
-|   `-- reference/segment-layout.md  core 1.0, box layout 3.2, stream layout 1.4, names and protocols
+|   `-- reference/segment-layout.md  core 1.0, box layout 3.3, stream layout 1.5, names and protocols
 |-- includes/abbreviations.md  acronym tooltips appended to every page
 |-- zensical.toml              site configuration and navigation
 |-- .github/workflows/ci.yaml  lint, docs check, C++ tests, cibuildwheel wheels, tests, stress,
@@ -140,11 +149,11 @@ class's identity (the `identity` class keyword, by default
 always asks for a new name and raises `SegmentExistsError` if it is taken.
 
 Every segment starts with the same 64-byte line, whatever its kind. Core
-version 1.0, box layout 3.2, from offset 0:
+version 1.0, box layout 3.3, from offset 0:
 
 - Common line 0, written once at creation: `magic` (`SBX_BOX_` for a box,
   `SBX_STRM` for a stream), `core_major` 1, `core_minor` 0, `kind_major` 3,
-  `kind_minor` 2, `schema_hash`, `create_id`, `creator_start`,
+  `kind_minor` 3, `schema_hash`, `create_id`, `creator_start`,
   `creator_pidns`, `creator_pid`, `waiter_slots`, `size`.
 - Box line 1, at offset 64: `seq` (sequence lock; the generation is
   `seq >> 1`, there is no generation field), `writer_pid`, `wake_word`,
@@ -161,8 +170,13 @@ version 1.0, box layout 3.2, from offset 0:
   `asleep_on`: the offset of the count the slot's current wait added 1 to,
   which freeing a dead owner's slot takes back), then the description
   table of `types_size` bytes. Kinds are 0 to 5, 6 to 12 (fixed-size
-  scalars), 13 to 23 (fixed-width numbers and `datetime64`) and 64 to 75
-  (described types; 75, an array up to a maximum shape, only in a stream).
+  scalars), 13 to 23 (fixed-width numbers and `datetime64`), and 64 to 77
+  (described types; 75, an array up to a maximum shape, in a stream
+  item or a box field, written as its shape line and the elements in use;
+  76, an attribute, a box field only, holding the request part, the value
+  part with `published` and the setpoint; 77, a value with an
+  `i64` timestamp in ns, wherever a record may go, its timestamp `-2**63`
+  replaced by the time of the write).
 - The record, at a multiple of 64. `record + record_size <= 2**32 - 4096`.
 - The metadata area, when `metadata` is not 0, at the first multiple of 64
   after the record, `metadata + metadata_size <= 2**32 - 4096`: a 64-byte
@@ -186,7 +200,7 @@ A stream's segment starts with a 256-byte header: the common line, a line
 of geometry written once, the sender's line and the readers' line. Then
 come a 64-byte entry per reader, the waiter slots, `capacity` slots each
 holding a `seq` and one item, the description table, and the metadata
-area laid out as a box's. Stream layout 1.4 keeps `metadata_size` and
+area laid out as a box's. Stream layout 1.5 keeps `metadata_size` and
 `metadata` in the geometry line and `metadata_head` in the sender's line.
 Every offset is 64-bit. The full specification is in
 `docs/reference/segment-layout.md`.
@@ -204,8 +218,10 @@ capacity counts elements, 1 to 1048576.
 
 ### Lifecycle
 
-- `close()` interrupts and stops the watcher thread, stops forwarding
-  started with `events.follow`, and detaches this box. Later reads and
+- `close()` interrupts and stops the watcher thread, stops the box's
+  request servers, releasing each field, and cancels its pending request
+  futures, stops forwarding started with `events.follow`, and detaches
+  this box. Later reads and
   writes raise `BoxClosedError`. Garbage collection closes a box too, but
   forwarding it started keeps running until the cycle collector frees its
   events groups.
@@ -354,6 +370,9 @@ A read decodes the stored bytes; a value that cannot be changed (a
 `datetime`, or a frozen record, tuple or frozenset holding only such values)
 is reused until its field is written. `update(**values)` writes several
 fields at once; `watch(field)` and `events` report changes from any process.
+A field declared `Attr[T]` with `attr()` is published by its owner with
+`publish` and read by any process, and may take requests the owner serves;
+see `docs/how-to/request-work-from-the-owner.md`.
 C++ and C code take a box through `__sharedbox_box__` or open it by name; see
 `docs/how-to/accept-a-box-in-cpp.md`, `docs/how-to/accept-a-box-in-c.md` and
 `docs/how-to/open-a-box-from-a-program.md`.

{sharedbox-0.8.0 → sharedbox-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sharedbox
-Version: 0.8.0
+Version: 0.9.0
 Summary: Python containers using shared memory.
 Author-Email: Jacopo Abramo <jacopo.abramo@gmail.com>
 License-Expression: Apache-2.0

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/examples/clean_up_segments.py

@@ -1,7 +1,7 @@
 """The script of the guide "How to clean up segments"."""
 
 # --8<-- [start:close]
-from sharedbox import LockTimeoutError, SharedBox
+from sharedbox import LockTimeoutError, SharedBox, segment_status
 
 
 class Delivery(SharedBox, name="example-delivery"):
@@ -18,6 +18,10 @@ delivery.close()
 Delivery.unlink()
 # --8<-- [end:unlink]
 
+# --8<-- [start:status]
+print(segment_status("example-delivery"))  # missing
+# --8<-- [end:status]
+
 creator = Delivery(True)
 
 # --8<-- [start:force-unlock]

sharedbox-0.9.0/docs/examples/request_work_from_the_owner.py

@@ -0,0 +1,95 @@
+"""The script of the guide "How to request work from the process that owns a box"."""
+
+# --8<-- [start:declare]
+import asyncio
+import threading
+
+from sharedbox import Attr, RequestError, RequestSupersededError, SharedBox, attr
+
+
+class Camera(SharedBox, name="example-camera"):
+    temperature: Attr[float] = attr(timed=True)
+    exposure: Attr[float] = attr(timed=True, settable=True, default=0.01)
+    move: Attr[float, [float]] = attr()
+    home: Attr[None] = attr()
+
+
+# --8<-- [end:declare]
+
+# --8<-- [start:publish]
+camera = Camera()
+camera.temperature.publish(value=21.5)
+print(camera.temperature.value)  # 21.5
+reading = camera.temperature.read()
+print(reading["value"], reading["timestamp_ns"] > 0)  # 21.5 True
+# --8<-- [end:publish]
+
+
+# --8<-- [start:serve]
+def set_exposure(value: float) -> float:
+    accepted = min(max(value, 0.001), 1.0)
+    camera.exposure.publish(setpoint=accepted)
+    camera.exposure.publish(value=accepted)
+    return accepted
+
+
+def move(target: float) -> float:
+    if target > 100.0:
+        raise ValueError(f"{target} is out of range")
+    return target
+
+
+exposure_server = camera.exposure.serve(set_exposure)
+move_server = camera.move.serve(move)
+# --8<-- [end:serve]
+
+# --8<-- [start:request]
+print(camera.exposure.set(5.0).result(timeout=5))  # 1.0
+print(camera.exposure.setpoint)  # 1.0
+print(camera.move(5.0).result(timeout=5))  # 5.0
+
+
+async def main() -> None:
+    print(await camera.exposure.set(0.02))  # 0.02
+
+
+asyncio.run(main())
+# --8<-- [end:request]
+
+# --8<-- [start:error]
+try:
+    camera.move(250.0).result(timeout=5)
+except RequestError as error:
+    print(error)  # Camera.move: ValueError: 250.0 is out of range
+# --8<-- [end:error]
+
+move_server.stop()
+
+# --8<-- [start:supersede]
+started = threading.Event()
+release = threading.Event()
+
+
+def slow_move(target: float) -> float:
+    started.set()
+    release.wait()
+    return target
+
+
+move_server = camera.move.serve(slow_move)
+first = camera.move(1.0)
+started.wait()
+second = camera.move(2.0)
+third = camera.move(3.0)
+release.set()
+print(first.result(timeout=5), third.result(timeout=5))  # 1.0 3.0
+try:
+    second.result(timeout=5)
+except RequestSupersededError:
+    print("the second request was superseded")
+# --8<-- [end:supersede]
+
+move_server.stop()
+exposure_server.stop()
+camera.close()
+Camera.unlink()

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/examples/send_items_through_a_stream.py

@@ -12,6 +12,7 @@ from sharedbox import (
     Capacity,
     DType,
     EndOfStream,
+    ItemGoneError,
     MaxShape,
     ReaderReleased,
     Shape,
@@ -43,6 +44,23 @@ def register(stream: SharedStream[Letter], ready: "mp.synchronize.Event") -> Non
 # --8<-- [end:reader]
 
 
+# --8<-- [start:fetch]
+def fetch_letters(reader: SharedReceiveStream[Letter], first: int, last: int) -> None:
+    position = first
+    while position <= last:
+        try:
+            letter = reader.fetch(position, timeout=5)
+        except ItemGoneError as gone:
+            print("skipped", position, "to", gone.oldest - 1)
+            position = gone.oldest
+            continue
+        print("fetched", letter.index)
+        position += 1
+
+
+# --8<-- [end:fetch]
+
+
 # --8<-- [start:tasks]
 async def produce(sender: SharedSendStream[Letter]) -> None:
     async with sender:
@@ -185,3 +203,10 @@ if __name__ == "__main__":
             sort_without_stalling(sender, 6)
         file_letters(reader)
     SharedStream.unlink("example-sorting:release")
+    with SharedStream.create(Letter, "example-sorting:fetch", capacity=8) as stream:
+        reader = stream.reader(mode="lossy")
+        with stream.sender() as sender:
+            for i in range(6):
+                sender.send(Letter(i, "Ada", np.full((32, 32), i, np.uint8)))
+        fetch_letters(reader, 2, 4)
+    SharedStream.unlink("example-sorting:fetch")

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/examples/store_a_large_list.py

@@ -15,7 +15,7 @@ class Recording(SharedBox, name="example-recording"):
 # --8<-- [end:declare]
 
 # --8<-- [start:create]
-recording = Recording(BoundedList[float]([0.0] * 50000, capacity=65536))
+recording = Recording(BoundedList(float, [0.0] * 50000, capacity=65536))
 # --8<-- [end:create]
 
 # --8<-- [start:change]

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/examples/store_a_large_set_or_dict.py

@@ -13,7 +13,7 @@ class Catalogue(SharedBox, name="example-catalogue"):
 # --8<-- [end:declare]
 
 # --8<-- [start:create]
-catalogue = Catalogue(BoundedSet[int](range(50000), capacity=65536))
+catalogue = Catalogue(BoundedSet(int, range(50000), capacity=65536))
 # --8<-- [end:create]
 
 # --8<-- [start:change]
@@ -80,7 +80,7 @@ class Scores(SharedBox, name="example-scores"):
     by_id: Annotated[BoundedDict[int, float], Capacity(4096)]
 
 
-scores = Scores(BoundedDict[int, float](dict.fromkeys(range(3000), 1.0), capacity=4096))
+scores = Scores(BoundedDict(int, float, dict.fromkeys(range(3000), 1.0), capacity=4096))
 by_id = scores.by_id
 print(by_id[2999], by_id.get(5000), 5000 in by_id)  # 1.0 None False
 # --8<-- [end:dict-declare]

sharedbox-0.9.0/docs/examples/store_a_value_with_its_time.py

@@ -0,0 +1,49 @@
+"""The script of the guide "How to store a value with its time"."""
+# ruff: noqa: RUF012
+
+# --8<-- [start:declare]
+from typing import Annotated
+
+from sharedbox import Capacity, SharedBox, SharedStream, Timed
+
+
+class Thermometer(SharedBox, name="example-thermometer"):
+    temperature: Timed[float] = Timed(0.0, 0)
+    status: Timed[Annotated[str, Capacity(16)]] = Timed("", 0)
+    history: Annotated[list[Timed[float]], Capacity(4)] = []
+
+
+# --8<-- [end:declare]
+
+# --8<-- [start:stamp]
+thermometer = Thermometer()
+thermometer.temperature = Timed.now(21.5)
+reading = thermometer.temperature
+print(reading.value)  # 21.5
+print(reading.timestamp_ns > 0)  # True
+print(type(reading.timestamp))  # <class 'float'>
+# --8<-- [end:stamp]
+
+# --8<-- [start:given]
+device_ns = 1_762_000_000_123_456_789
+thermometer.status = Timed("ready", device_ns)
+print(thermometer.status)  # Timed(value='ready', timestamp_ns=1762000000123456789)
+# --8<-- [end:given]
+
+# --8<-- [start:collections]
+thermometer.history = [Timed.now(21.4), Timed.now(21.5)]
+first, second = thermometer.history
+print(first.timestamp_ns == second.timestamp_ns)  # True
+# --8<-- [end:collections]
+
+# --8<-- [start:stream]
+with SharedStream.create(Timed[float], "example-temperatures", capacity=4) as stream:
+    reader = stream.reader()
+    with stream.sender() as sender:
+        sender.send(Timed.now(21.6))
+    print(reader.receive().value)  # 21.6
+# --8<-- [end:stream]
+
+thermometer.close()
+Thermometer.unlink()
+SharedStream.unlink("example-temperatures")

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/examples/store_arrays.py

@@ -7,7 +7,7 @@ from typing import Annotated
 import numpy as np
 import numpy.typing as npt
 
-from sharedbox import DType, Shape, SharedBox, SupportsDLPack, field
+from sharedbox import DType, MaxShape, Shape, SharedBox, SupportsDLPack, field
 
 
 class Scanner(SharedBox, name="example-scanner"):
@@ -54,6 +54,23 @@ with scanner.writing("scan") as scan:
 print(int(scanner.scan[0].sum()))  # 1530
 # --8<-- [end:writing]
 
+
+# --8<-- [start:max-shape]
+class Sorter(SharedBox, name="example-sorter"):
+    label: Annotated[npt.NDArray[np.uint8], MaxShape((8, 12))] = np.zeros(
+        (0, 12), np.uint8
+    )
+
+
+sorter = Sorter()
+print(sorter.label.shape)  # (0, 12)
+sorter.label = np.ones((3, 12), np.uint8)
+print(sorter.label.shape)  # (3, 12)
+with sorter.writing("label", shape=(5, 12)) as label:
+    label[:] = 2
+print(sorter.label.shape, int(sorter.label.sum()))  # (5, 12) 120
+# --8<-- [end:max-shape]
+
 # --8<-- [start:any-library]
 raw = scanner.raw
 print(np.from_dlpack(raw))  # [0. 0. 0.]
@@ -85,5 +102,7 @@ scanner.close()
 Scanner.unlink()
 tray.close()
 Tray.unlink()
+sorter.close()
+Sorter.unlink()
 binder.close()
 Binder.unlink()

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/explanation/field-types.md

@@ -57,6 +57,7 @@ containers: "records, collections and arrays" {
   "set, frozenset, tuple[T, ...]": "as a list"
   "dict": "as a list, with a key and value in each slot"
   "array uint8, shape (2, 2)": "01 02 03 04, in C order"
+  "Timed[int] = Timed(5, t)": "05 00 00 00 00 00 00 00 | t, nanoseconds as an int"
   "SharedBox subclass": "create id | schema hash | name, 256 bytes"
 }
 ```

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/explanation/glossary.md

@@ -11,6 +11,12 @@ word you don't know, its link brings you to this page.
 Acronyms are explained in tooltips across the site: hover over a word with
 a dotted underline to read what it stands for.
 
+### Attribute
+
+An attribute is a [field](#field) declared with [`Attr`][sharedbox.Attr].
+It holds a value its owner publishes and, when it takes requests, a request
+part through which other processes ask the owner to act.
+
 ### Box
 
 A box is a record that several processes share. You describe it with a

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/how-to/attach-metadata.md

@@ -105,8 +105,9 @@ the slot that [`writing`][sharedbox.SharedSendStream.writing] gives take
 the keyword too. A version applies from the item sent with it, and a
 reader's [`metadata`][sharedbox.SharedReceiveStream.metadata] and
 [`metadata_version`][sharedbox.SharedReceiveStream.metadata_version]
-describe the item it received last, so the reader can tell which version
-each item was sent under. The metadata of this stream is a `TypedDict` too:
+describe the item it returned last, by a receive or a fetch, so the reader
+can tell which version each item was sent under. The metadata of this stream
+is a `TypedDict` too:
 
 ```{.python}
 --8<-- "docs/examples/attach_metadata.py:calibration"
@@ -144,7 +145,7 @@ latest reader meets this first, because the sender may overwrite its item
 right after the reader receives it.
 
 !!! warning "A callback on the main thread can see a later item's version"
-    The reader's `metadata` follows the item the reader received last,
+    The reader's `metadata` follows the item the reader returned last,
     which may be later than the item a callback was given. A callback of
     [`reader.events`][sharedbox.SharedReceiveStream.events] connected with
     `thread="main"` runs after the reader's thread has received its item,

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/how-to/clean-up-segments.md

@@ -45,7 +45,20 @@ handle is closed. Either way you write the same code, and it works on both.
 ## Remove a segment left by a crash
 
 On Linux, a process that crashed before calling `unlink` leaves its segment
-behind as a file in `/dev/shm`. You can list them:
+behind as a file in `/dev/shm`. For one name,
+[`segment_status`][sharedbox.segment_status] says whether a box or stream
+is published under it and whether the process that created it still runs:
+
+```{.python}
+--8<-- "docs/examples/clean_up_segments.py:status"
+```
+
+It returns `missing`, `running` or `creator_exited`. A segment whose creator
+has exited is one to remove once no other process uses it. A process that
+crashed in the middle of `create` leaves a segment that was never published,
+which reads as `missing` although the name is still taken; creating under
+that name raises `SegmentExistsError`, which says so. To see every segment at
+once, list the files:
 
 ```bash
 ls /dev/shm/SBX:*

{sharedbox-0.8.0 → sharedbox-0.9.0}/docs/how-to/index.md

@@ -26,6 +26,8 @@ items through a [stream](../explanation/glossary.md#stream).
   capacity and handle values that do not fit
 - [How to store records](store-records.md): dataclasses, named tuples and
   typed dicts as one field
+- [How to store a value with its time](store-a-value-with-its-time.md):
+  a timestamp the write takes, or one you already have
 - [How to store lists, sets and dicts](store-collections.md): collections
   with a capacity in elements
 - [How to store arrays](store-arrays.md): a shape, a dtype and any DLPack
@@ -38,6 +40,9 @@ items through a [stream](../explanation/glossary.md#stream).
   write with `update` and read with `snapshot`
 - [How to send a box to another process](send-a-box-to-another-process.md):
   as an argument, by name, or to a pool
+- [How to request work from the process that owns a box](request-work-from-the-owner.md):
+  attributes the owner publishes, requests it answers, and what happens
+  when one fails
 - [How to clean up segments](clean-up-segments.md): close, unlink, and
   recover after a crash
 - [How to follow a whole reference graph](follow-a-whole-reference-graph.md):