Say in the docs that a remote array can be filled, not only read

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: FrancescAlted

RELEASE_NOTES.md

@@ -22,6 +22,17 @@ XXX version-specific blurb XXX
   which an object store has no way to serve), so constructors given a URL now say
   that instead of failing deep in C.
 
+* A `C2Array` can be written to a chunk at a time, which is how several
+  processes fill one remote array at once: `update_chunk()` (and its async
+  `aupdate_chunk()`) posts one compressed chunk into a slot of a pre-sized
+  array, and `written_chunks()` says which slots hold anything yet. The array is
+  laid out with `blosc2.uninit()` and uploaded -- a couple of hundred bytes
+  whatever its size -- and each slot is written once: a second write raises
+  `blosc2.ChunkAlreadyWritten`, which is the whole of the coordination between
+  writers. Writing into an empty slot appends to the frame and moves no other
+  chunk, so a fill is cheap and a concurrent reader's cached offsets stay good.
+  Needs a Caterva2 subscriber that serves the endpoint.
+
 * `Proxy.fetch()` takes a `max_concurrency=` argument, and reads it from the
   source when the source has one, so `blosc2.open(url, lazy=True,
   max_concurrency=...)` overlaps its chunk fetches in a thread pool. Ordinary

doc/reference/c2array.rst

@@ -14,6 +14,16 @@ HDF5 leaf) is fetched a whole chunk at a time, as everything was before.  Which
 one this is takes at most one request to find out, and is decided once --
 :meth:`C2Array.block_source` is what answers it.
 
+A stored remote array can also be *filled*, by as many writers at once as it has
+chunks.  The array is laid out first -- ``blosc2.uninit`` writes a couple of
+hundred bytes whatever its size -- and then each writer posts the chunks it owns
+with :meth:`C2Array.update_chunk`.  A slot nothing was written to is free, and a
+write claims it; a second write to the same slot raises
+:class:`blosc2.ChunkAlreadyWritten`, so two writers that both believe they own a
+chunk are resolved by the array rather than by anything either of them holds.
+:meth:`C2Array.written_chunks` reads how far the fill has got out of the frame's
+own offsets, which is one range read and no endpoint of its own.
+
 
 .. currentmodule:: blosc2