Skip to main content

NeonReadStream

Struct NeonReadStream 

pub struct NeonReadStream<'a, T: SqlTransport> { /* private fields */ }
Available on crate feature event-store only.
Expand description

The read “stream”: one round trip, then a buffer being drained.

§This is the honest part of the crate

EventStore::read’s doc comment says the stream is what “lets an adapter stream a million-event replay without buffering it”. This adapter cannot do that and no version of it ever will, because Neon’s /sql endpoint has no cursor: the response is one JSON document, capped at MAX_RESPONSE_BYTES, and it either arrives whole or fails with NeonError::ResponseTooLarge. The Stream impl below is therefore a shape, not a capability — it satisfies the port’s signature exactly and honours roughly none of the port’s prose.

The one property it does honour is laziness. read is not async, so nothing is sent when it is called; the request sits unsent in the state machine below until the first poll_next. That is load-bearing on wasm32, where issuing a fetch outside a polled future is not merely wasteful but happens off the event loop the runtime owns.

§ES-11: what is free, and what the transport’s fence buys

Half of ES-11 is free here and the other half is bought, and the difference is worth stating where a caller meets it. One read is one statement, so there is no second sample for the answer to drift against: the paging defect ES-11 is mostly about — a store that re-queries per page and grows under the caller’s feet — is unreachable by construction.

The other half is that the snapshot the endpoint takes precedes an append this caller issues immediately afterwards. The request is dispatched at the first poll, the earliest the port permits, and on its own it is one of two independent requests to a proxy that hands each to whichever backend it likes: no session, no queue and no protocol ordering between them.

So the order is bought at the transport instead. A conforming SqlTransport registers this read when the first poll dispatches it and settles it when the endpoint answers, and append waits on SqlTransport::reads_settled before it sends anything. An answer follows the statement’s execution, so the snapshot precedes the write: an order the endpoint honours, which ADR-0061 requires and spawn order alone never gave.

The release is driven by the transport, never by polling this stream — a stream polled once and set aside does not hold an append back forever. An unpolled stream has dispatched nothing and costs an append nothing.

Without the fence the race was observed: over the conformance transport read_result_is_stable_under_concurrent_append failed intermittently, always with the read seeing an event appended after it was issued. ADR-0087 records the live sweep that measured the race with the fence and without it, and the rate it found; the fence is what this crate ships since 0.4.0.

The ordering domain is one transport value: reads and appends through clones of one transport are ordered, and those through independent transports are not — a stated limit of this store’s ES-11 claim, which no rule can observe through the port. ADR-0087 records the claim as met for operations that share one transport, and stated as such.

Trait Implementations§

§

impl<T: SqlTransport> Debug for NeonReadStream<'_, T>

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl<T: SqlTransport> Stream for NeonReadStream<'_, T>

§

type Item = Result<SequencedEvent, NeonError<<T as SqlTransport>::Error>>

Values yielded by the stream.
§

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted. Read more
§

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream. Read more

Auto Trait Implementations§

§

impl<'a, T> !RefUnwindSafe for NeonReadStream<'a, T>

§

impl<'a, T> !Send for NeonReadStream<'a, T>

§

impl<'a, T> !Sync for NeonReadStream<'a, T>

§

impl<'a, T> !UnwindSafe for NeonReadStream<'a, T>

§

impl<'a, T> Freeze for NeonReadStream<'a, T>
where ReadState<'a, T>: Freeze,

§

impl<'a, T> Unpin for NeonReadStream<'a, T>
where ReadState<'a, T>: Unpin,

§

impl<'a, T> UnsafeUnpin for NeonReadStream<'a, T>
where ReadState<'a, T>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<S, T, E> TryStream for S
where S: Stream<Item = Result<T, E>> + ?Sized,

§

type Ok = T

The type of successful values yielded by this future
§

type Error = E

The type of failures yielded by this future
§

fn try_poll_next( self: Pin<&mut S>, cx: &mut Context<'_>, ) -> Poll<Option<Result<<S as TryStream>::Ok, <S as TryStream>::Error>>>

Poll this TryStream as if it were a Stream. Read more