a11::stores::ChunkStoreReader Class Reference

An ordered, buffered read cursor over a ChunkStore. More...

#include <cpp/a11/stores/chunk_store_reader.h>

Classes
struct	State

Public Member Functions
	~ChunkStoreReader ()=default
void	EnsureStarted ()
	Start the background read pump if it is not already running.
void	Cancel ()
	Stop the background read pump.
absl::Status	GetStatus () const
	Get the reader's current status.
a11::Task	Done () const
	Await completion of the background read pump.
a11::Future< std::optional< data::NodeFragment > >	Next (absl::Duration timeout=absl::InfiniteDuration())
	Get the next fragment from the store.
a11::Future< std::vector< std::optional< data::NodeFragment > > >	NextMany (size_t limit, absl::Duration timeout=absl::InfiniteDuration())
	Get up to limit fragments in one await.
std::shared_ptr< ChunkStore >	store () const
ChunkStoreReaderOptions	options () const
size_t	buffer_size () const

Static Public Member Functions
static absl::StatusOr< std::shared_ptr< ChunkStoreReader > >	Create (std::shared_ptr< ChunkStore > store, ChunkStoreReaderOptions options={})
	Create a reader over store.

Detailed Description

An ordered, buffered read cursor over a ChunkStore.

A reader pulls data::NodeFragment values out of a store, prefetching ahead into a bounded buffer per its ChunkStoreReaderOptions. A background pump fetches fragments; callers await Next() to consume them. It is a first-class object that can be driven directly, though most code reaches one through a node. State is reference-counted and held via shared_ptr.

Constructor & Destructor Documentation

~ChunkStoreReader()

a11::stores::ChunkStoreReader::~ChunkStoreReader ( )

default

Member Function Documentation

buffer_size()

size_t a11::stores::ChunkStoreReader::buffer_size

(

)

const

Returns

The number of prefetched fragments currently buffered.

Cancel()

void a11::stores::ChunkStoreReader::Cancel

(

)

Stop the background read pump.

Pending Next() awaitables are resolved and no further fragments are fetched.

Create()

absl::StatusOr< std::shared_ptr< ChunkStoreReader > > a11::stores::ChunkStoreReader::Create ( std::shared_ptr< ChunkStore >  store, ChunkStoreReaderOptions  options = {}  )

static

Create a reader over store.

Parameters

store	The store to read fragments from.
options	Tuning for ordering, buffering, offset, pop-on-read behavior, and sticky-mimetype expansion.

Returns

A shared, ready-to-use reader, or an error status if the options are invalid.

Done()

a11::Task a11::stores::ChunkStoreReader::Done

(

)

const

Await completion of the background read pump.

Returns

An awaitable that resolves once the reader has drained the store or been cancelled.

EnsureStarted()

void a11::stores::ChunkStoreReader::EnsureStarted

(

)

Start the background read pump if it is not already running.

Reading normally starts the pump lazily; call this to begin buffering before the first Next().

GetStatus()

absl::Status a11::stores::ChunkStoreReader::GetStatus

(

)

const

Get the reader's current status.

Returns

The status distinguishing a healthy stream from one that has failed or ended.

Next()

a11::Future< std::optional< data::NodeFragment > > a11::stores::ChunkStoreReader::Next

(

absl::Duration

timeout = absl::InfiniteDuration()

)

Get the next fragment from the store.

Parameters

timeout

The maximum duration to wait before giving up.

Returns

An awaitable that resolves with the next fragment, or an empty optional at end of stream.

NextMany()

a11::Future< std::vector< std::optional< data::NodeFragment > > > a11::stores::ChunkStoreReader::NextMany	(	size_t	limit,
		absl::Duration	timeout = absl::InfiniteDuration()
	)

Get up to limit fragments in one await.

Greedy but never patient: it returns everything already prefetched, up to limit, and only waits at all when nothing is buffered – in which case it waits for exactly one fragment and returns that. So a caller draining a node that is already full pays one await per batch instead of one per fragment, and a caller reading a live stream still sees each value as soon as it arrives rather than waiting for a batch to fill.

This matters most above the binding: in Python every await costs an event-loop turn, so a per-fragment await caps a drain at a few thousand values a second no matter how fast the store is.

Parameters

limit	Maximum fragments to return. Must be positive.
timeout	The maximum duration to wait, and only ever waited when the buffer is empty.

Returns

An awaitable resolving to between one and limit entries. A trailing empty optional marks end of stream, exactly as Next() does.

options()

ChunkStoreReaderOptions a11::stores::ChunkStoreReader::options

(

)

const

Returns

The options this reader was created with.

store()

std::shared_ptr< ChunkStore > a11::stores::ChunkStoreReader::store

(

)

const

Returns

The store this reader draws fragments from.

---

The documentation for this class was generated from the following files:

• cpp/a11/stores/chunk_store_reader.h
• cpp/a11/stores/chunk_store_reader.cc