SC::AsyncReadableStream Struct Reference

Async source abstraction emitting data events in caller provided byte buffers. More...

#include <AsyncStreams.h>

Inheritance diagram for SC::AsyncReadableStream:

Classes
struct	Request

Public Member Functions
Result	init (AsyncBuffersPool &buffersPool)
	Emitted when the underlying resource has been closed.
Result	start ()
	Starts the readable stream, that will emit eventData.
void	pause ()
	Pauses the readable stream (that can be later resumed)
void	resumeReading ()
	Resumes the readable stream paused by AsyncReadableStream::pause.
void	destroy ()
	Forcefully destroys the readable stream before calling end event releasing all resources.
bool	isEnded () const
	Returns true if the stream is ended (AsyncReadableStream::end has been called)
bool	hasBeenDestroyed () const
	Returns true if the stream has been already destroyed (asynchronously through destroy())
AsyncBuffersPool &	getBuffersPool ()
	Obtains the AsyncBuffersPool to request more buffers.
constexpr void	setReadQueue (Span< Request > requests)
	Sets the read queue for this readable stream.
size_t	getReadQueueSize () const
	Returns the size of read queue.
bool	push (AsyncBufferView::ID bufferID, size_t newSize)
	Use push from inside AsyncReadableStream::asyncRead function to queue received data.
Result	unshift (AsyncBufferView::ID bufferID)
	Push back a buffer to the front of the read queue (e.g. for un-consumed data)
void	pushEnd ()
	Use pushEnd from inside AsyncReadableStream::asyncRead to signal production end.
void	reactivate (bool doReactivate)
	Use reactivate(true) from inside AsyncReadableStream::asyncRead function to ask the state machine to invoke asyncRead again.
void	emitError (Result error)
	Signals an async error received.
bool	getBufferOrPause (size_t minumumSizeInBytes, AsyncBufferView::ID &bufferID, Span< char > &data)
	Returns an unused buffer from pool or pauses the stream if none is available.
void	setAutoDestroy (bool value)
	If set to true will automatically call .destroy() when Ended state is reached.
bool	getAutoDestroy () const
	Returns true if stream will automatically call .destroy() when Ended state is reached.

Public Attributes
Event< MaxListeners, Result >	eventError
Event< MaxListeners, AsyncBufferView::ID >	eventData
	Emitted when an error occurs.
Event< MaxListeners >	eventEnd
	Emitted when a new buffer has been read.
Event< MaxListeners >	eventClose
	Emitted when there is no more data.

Static Public Attributes
static constexpr int	MaxListeners = 8

Protected Member Functions
virtual Result	asyncRead ()=0
	Function that every stream must define to implement its custom read operation.
virtual Result	asyncDestroyReadable ()
	Function that a readable stream can re-implement to release its internal resources.
Result	finishedDestroyingReadable ()
	Called from inside asyncDestroy to transition from Destroying to Destroyed state (emitting eventClose)

Detailed Description

Async source abstraction emitting data events in caller provided byte buffers.

After AsyncReadableStream::start it will start emitting AsyncReadableStream::eventData with buffers. User must provide a custom async red implementation in AsyncReadableStream::asyncRead. The stream must be paused when the AsyncBuffersPool is full (use AsyncReadableStream::getBufferOrPause). Once the stream is ended, it will emit AsyncReadableStream::eventEnd and it cannot be used further. AsyncReadableStream::eventError will be emitted when an error occurs in any phase.

Member Function Documentation

asyncDestroyReadable()

virtual Result SC::AsyncReadableStream::asyncDestroyReadable ( )

protectedvirtual

Function that a readable stream can re-implement to release its internal resources.

Note

The re-implementation MUST call finishedDestroyingReadable once it has finished stopping.

Reimplemented in SC::AsyncRequestReadableStream< AsyncRequestType >, SC::AsyncRequestReadableStream< AsyncFileRead >, and SC::AsyncRequestReadableStream< AsyncSocketReceive >.

asyncRead()

virtual Result SC::AsyncReadableStream::asyncRead ( )

protectedpure virtual

Function that every stream must define to implement its custom read operation.

Implemented in SC::AsyncDuplexStream, SC::AsyncRequestReadableStream< AsyncRequestType >, SC::AsyncRequestReadableStream< AsyncFileRead >, and SC::AsyncRequestReadableStream< AsyncSocketReceive >.

destroy()

void SC::AsyncReadableStream::destroy

(

)

Forcefully destroys the readable stream before calling end event releasing all resources.

Note

It's safe to call destroy in any state and also when already destroyed (it's idempotent)

emitError()

void SC::AsyncReadableStream::emitError

(

Result

error

)

Signals an async error received.

finishedDestroyingReadable()

Result SC::AsyncReadableStream::finishedDestroyingReadable ( )

protected

Called from inside asyncDestroy to transition from Destroying to Destroyed state (emitting eventClose)

getAutoDestroy()

bool SC::AsyncReadableStream::getAutoDestroy ( ) const

inlinenodiscard

Returns true if stream will automatically call .destroy() when Ended state is reached.

getBufferOrPause()

bool SC::AsyncReadableStream::getBufferOrPause ( size_t minumumSizeInBytes, AsyncBufferView::ID & bufferID, Span< char > & data )

nodiscard

Returns an unused buffer from pool or pauses the stream if none is available.

getBuffersPool()

AsyncBuffersPool & SC::AsyncReadableStream::getBuffersPool

(

)

Obtains the AsyncBuffersPool to request more buffers.

getReadQueueSize()

size_t SC::AsyncReadableStream::getReadQueueSize ( ) const

inlinenodiscard

Returns the size of read queue.

hasBeenDestroyed()

bool SC::AsyncReadableStream::hasBeenDestroyed ( ) const

inlinenodiscard

Returns true if the stream has been already destroyed (asynchronously through destroy())

init()

Result SC::AsyncReadableStream::init

(

AsyncBuffersPool &

buffersPool

)

Emitted when the underlying resource has been closed.

Inits the readable stream with an AsyncBuffersPool instance that will provide memory for it

Parameters

buffersPool

An instance of AsyncBuffersPool providing read buffers

Note

Remember to call AsyncReadableStream::setReadQueue before calling init

isEnded()

bool SC::AsyncReadableStream::isEnded ( ) const

inlinenodiscard

Returns true if the stream is ended (AsyncReadableStream::end has been called)

pause()

void SC::AsyncReadableStream::pause

(

)

Pauses the readable stream (that can be later resumed)

push()

bool SC::AsyncReadableStream::push ( AsyncBufferView::ID bufferID, size_t newSize )

nodiscard

Use push from inside AsyncReadableStream::asyncRead function to queue received data.

Returns

true if the caller can continue pushing

pushEnd()

void SC::AsyncReadableStream::pushEnd

(

)

Use pushEnd from inside AsyncReadableStream::asyncRead to signal production end.

reactivate()

void SC::AsyncReadableStream::reactivate

(

bool

doReactivate

)

Use reactivate(true) from inside AsyncReadableStream::asyncRead function to ask the state machine to invoke asyncRead again.

resumeReading()

void SC::AsyncReadableStream::resumeReading

(

)

Resumes the readable stream paused by AsyncReadableStream::pause.

setAutoDestroy()

void SC::AsyncReadableStream::setAutoDestroy ( bool value )

inline

If set to true will automatically call .destroy() when Ended state is reached.

setReadQueue()

void SC::AsyncReadableStream::setReadQueue ( Span< Request > requests )

inlineconstexpr

Sets the read queue for this readable stream.

start()

Result SC::AsyncReadableStream::start

(

)

Starts the readable stream, that will emit eventData.

unshift()

Result SC::AsyncReadableStream::unshift

(

AsyncBufferView::ID

bufferID

)

Push back a buffer to the front of the read queue (e.g. for un-consumed data)

Member Data Documentation

eventClose

Event<MaxListeners> SC::AsyncReadableStream::eventClose

Emitted when there is no more data.

eventData

Event<MaxListeners, AsyncBufferView::ID> SC::AsyncReadableStream::eventData

Emitted when an error occurs.

eventEnd

Event<MaxListeners> SC::AsyncReadableStream::eventEnd

Emitted when a new buffer has been read.

---

The documentation for this struct was generated from the following file:

• AsyncStreams.h