Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 157 additions & 27 deletions packages/zarr-storage/DESIGN.md

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions packages/zarr-storage/changes/464.feature.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add `Context`, the resources a `zarr-storage` store's operations draw on: a `ThreadPool` and a `Limiter` per backend resource key, with process-wide defaults. Every store view carries a context (`Store(backend, context=...)`, `with_context`), stores sharing a context share its limits, and `store.limited(n)` bounds a burst of operations within the context's limit. `AsyncStore` now runs a sync-only backend on the context's thread pool, and batches run concurrently under the context.
8 changes: 6 additions & 2 deletions packages/zarr-storage/src/zarr_storage/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
A `Store` is a view of a backend at a root directory, used through sync methods; an `AsyncStore`
is the same view used through coroutines, with the same method names. Backends implement capability
protocols (`Readable`, `Writable`, `Listable`, their batch variants, and async twins) over backend
paths; the stores validate keys, apply their root, enforce read-only access, and are the only
objects most callers need.
paths; the stores validate keys, apply their root, enforce read-only access, schedule and limit
operations with the resources of their `Context`, and are the only objects most callers need.
"""

from zarr_storage._errors import (
Expand Down Expand Up @@ -39,6 +39,7 @@
WritableMany,
WritableManyAsync,
)
from zarr_storage._resources import Context, Limiter, ThreadPool
from zarr_storage._store import AsyncStore, Store
from zarr_storage._types import (
ByteRange,
Expand Down Expand Up @@ -67,6 +68,7 @@
"BatchError",
"ByteRange",
"ClosableAsync",
"Context",
"Copied",
"DeletableIfMatch",
"DeletableIfMatchAsync",
Expand All @@ -79,6 +81,7 @@
"InvalidKeyError",
"Key",
"KeyConflictError",
"Limiter",
"ListItem",
"Listable",
"ListableAsync",
Expand All @@ -101,6 +104,7 @@
"Store",
"StoreClosedError",
"SuffixRequest",
"ThreadPool",
"Unchanged",
"UnsupportedOperationError",
"Writable",
Expand Down
20 changes: 13 additions & 7 deletions packages/zarr-storage/src/zarr_storage/_batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@

if TYPE_CHECKING:
from collections.abc import AsyncIterator, Callable, Coroutine, Iterator, Sequence
from concurrent.futures import Executor, Future
from concurrent.futures import Future

from zarr_storage._resources import ThreadPool

__all__ = ["run_many", "run_many_async"]

Expand All @@ -27,13 +29,17 @@
def run_many(
fn: Callable[[Unpack[Ts]], R],
requests: Sequence[tuple[*Ts]],
executor: Executor | None = None,
pool: ThreadPool | None = None,
window: int = 1,
) -> Iterator[tuple[int, R]]:
"""Call `fn(*request)` for each request: one at a time, or on `executor`, `window` at once."""
if executor is None:
"""Call `fn(*request)` for each request: one at a time, or on `pool`, `window` at once.

Called from one of `pool`'s own threads, it runs one at a time on that thread: waiting there
for work queued behind it on the same pool could wait forever.
"""
if pool is None or pool.in_worker():
return _run_serially(fn, requests)
return _run_on(executor, fn, requests, window)
return _run_on(pool, fn, requests, window)


def _run_serially(
Expand All @@ -48,7 +54,7 @@ def _run_serially(


def _run_on(
executor: Executor,
pool: ThreadPool,
fn: Callable[[Unpack[Ts]], R],
requests: Sequence[tuple[*Ts]],
window: int,
Expand All @@ -59,7 +65,7 @@ def _run_on(
try:
while pending or (not errors and started < len(requests)):
while not errors and started < len(requests) and len(pending) < window:
pending[executor.submit(fn, *requests[started])] = started
pending[pool.submit(fn, *requests[started])] = started
started += 1
done, _ = wait(pending, return_when=FIRST_COMPLETED)
for future in done:
Expand Down
60 changes: 44 additions & 16 deletions packages/zarr-storage/src/zarr_storage/_protocols.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,22 @@
`/`.

Each capability has a sync protocol and an async twin whose methods end in `_async`. A backend
implements whichever it can. `Store` calls the sync protocols and `AsyncStore` the async ones, and
their methods are typed so that calling one the backend lacks is a type error. Compare-and-swap on a generation (`WritableIfMatch`, `DeletableIfMatch`) is a capability
of its own, since many stores can't do it; `put_if_absent` is part of `Writable`.
implements whichever it can. `Store` calls the sync protocols. `AsyncStore` calls the async twin
where the backend has it and otherwise runs the sync method on its context's thread pool, so a
backend that only blocks (a filesystem) needs no async code. Methods are typed so that calling one
the backend lacks is a type error. Compare-and-swap on a generation (`WritableIfMatch`,
`DeletableIfMatch`) is a capability of its own, since many stores can't do it; `put_if_absent` is
part of `Writable`.

Backends hold no thread pools or limits: the store schedules and limits every operation with the
resources of its `Context`, under the backend's `resource_key`. Backends must be thread-safe, since
a store runs their sync methods on many threads at once.

The batch capabilities (`ReadableMany`, `ReadableIntoMany`, `WritableMany` and their async twins)
are optional and change only speed: `Store.get_many` and its siblings work on any backend that
can read or write, one operation at a time, and use a backend's batch methods when it has them. A
batch method yields `(index, result)` pairs as operations finish and follows the failure rule of
`zarr_storage._batch`, whose runners implement it.
are for batching the store itself can do (one request for many keys, one GPU submission): without
them, `Store.get_many` and its siblings run single operations concurrently under the context's
resources. A batch method receives that context, so it can draw on the same resources; it yields
`(index, result)` pairs as operations finish and follows the failure rule of `zarr_storage._batch`.
"""

from __future__ import annotations
Expand All @@ -26,6 +33,7 @@
if TYPE_CHECKING:
from collections.abc import AsyncIterator, Iterator, Sequence

from zarr_storage._resources import Context
from zarr_storage._types import (
ByteRange,
Copied,
Expand Down Expand Up @@ -70,7 +78,17 @@


class Backend(Protocol):
"""What every backend provides: a lifecycle and whether it accepts writes at all."""
"""What every backend provides: a lifecycle, whether it accepts writes, and the key its
operations are limited under."""

@property
def resource_key(self) -> str:
"""The key of the `Limiter` that stores take from their context for this backend.

Backends that should share a limit by default share a key: every obstore S3 backend uses
`"obstore.S3Store"`, so a process's S3 requests are bounded together.
"""
...

@property
def closed(self) -> bool:
Expand Down Expand Up @@ -171,7 +189,7 @@ def delete_if_match(self, path: str, generation: Generation) -> Deleted | Reject
@runtime_checkable
class ReadableMany(Backend, Protocol):
def get_many(
self, requests: Sequence[tuple[str, ByteRange | None]]
self, requests: Sequence[tuple[str, ByteRange | None]], context: Context
) -> Iterator[tuple[int, Found | Missing]]:
"""`get` for each `(path, byte_range)`, yielding `(index, result)` as each finishes."""
...
Expand All @@ -180,19 +198,23 @@ def get_many(
@runtime_checkable
class ReadableIntoMany(Backend, Protocol[O_contra]):
def get_into_many(
self, requests: Sequence[tuple[str, O_contra, ByteRange | None]]
self, requests: Sequence[tuple[str, O_contra, ByteRange | None]], context: Context
) -> Iterator[tuple[int, Copied | Missing]]:
"""`get_into` for each `(path, out, byte_range)`, yielding `(index, result)`."""
...


@runtime_checkable
class WritableMany(Backend, Protocol):
def put_many(self, requests: Sequence[tuple[str, memoryview]]) -> Iterator[tuple[int, Written]]:
def put_many(
self, requests: Sequence[tuple[str, memoryview]], context: Context
) -> Iterator[tuple[int, Written]]:
"""`put` for each `(path, value)`, yielding `(index, result)` as each finishes."""
...

def delete_many(self, paths: Sequence[str]) -> Iterator[tuple[int, Deleted | Missing]]:
def delete_many(
self, paths: Sequence[str], context: Context
) -> Iterator[tuple[int, Deleted | Missing]]:
"""`delete` for each path, yielding `(index, result)` as each finishes."""
...

Expand All @@ -207,6 +229,7 @@ def list_dir(self, directory: str) -> Iterator[ListItem]:
...


@runtime_checkable
class ReadableAsync(Backend, Protocol):
async def get_async(self, path: str, byte_range: ByteRange | None) -> Found | Missing: ...

Expand All @@ -221,12 +244,14 @@ async def get_ranges_async(
async def head_async(self, path: str) -> ObjectMetadata | Missing: ...


@runtime_checkable
class ReadableIntoAsync(Backend, Protocol[O_contra]):
async def get_into_async(
self, path: str, out: O_contra, byte_range: ByteRange | None
) -> Copied | Missing: ...


@runtime_checkable
class WritableAsync(Backend, Protocol):
async def put_async(self, path: str, value: memoryview) -> Written: ...

Expand All @@ -237,12 +262,14 @@ async def delete_async(self, path: str) -> Deleted | Missing: ...
async def delete_dir_async(self, directory: str) -> None: ...


@runtime_checkable
class WritableIfMatchAsync(Backend, Protocol):
async def put_if_match_async(
self, path: str, value: memoryview, generation: Generation
) -> Written | Rejected | Missing: ...


@runtime_checkable
class DeletableIfMatchAsync(Backend, Protocol):
async def delete_if_match_async(
self, path: str, generation: Generation
Expand All @@ -252,28 +279,29 @@ async def delete_if_match_async(
@runtime_checkable
class ReadableManyAsync(Backend, Protocol):
def get_many_async(
self, requests: Sequence[tuple[str, ByteRange | None]]
self, requests: Sequence[tuple[str, ByteRange | None]], context: Context
) -> AsyncIterator[tuple[int, Found | Missing]]: ...


@runtime_checkable
class ReadableIntoManyAsync(Backend, Protocol[O_contra]):
def get_into_many_async(
self, requests: Sequence[tuple[str, O_contra, ByteRange | None]]
self, requests: Sequence[tuple[str, O_contra, ByteRange | None]], context: Context
) -> AsyncIterator[tuple[int, Copied | Missing]]: ...


@runtime_checkable
class WritableManyAsync(Backend, Protocol):
def put_many_async(
self, requests: Sequence[tuple[str, memoryview]]
self, requests: Sequence[tuple[str, memoryview]], context: Context
) -> AsyncIterator[tuple[int, Written]]: ...

def delete_many_async(
self, paths: Sequence[str]
self, paths: Sequence[str], context: Context
) -> AsyncIterator[tuple[int, Deleted | Missing]]: ...


@runtime_checkable
class ListableAsync(Backend, Protocol):
def list_async(self, directory: str) -> AsyncIterator[str]: ...

Expand Down
Loading
Loading