SC::AsyncWritableStream Struct Reference

Async destination abstraction where bytes can be written to. More...

#include <AsyncStreams.h>

Inheritance diagram for SC::AsyncWritableStream:

Classes
struct	Request

Public Member Functions
Result	init (AsyncBuffersPool &buffersPool)
	Emitted when the underlying resource has been closed.
constexpr void	setWriteQueue (Span< Request > requests)
	Sets the write queue for this writable stream.
size_t	getWriteQueueSize () const
	Returns the size of write queue.
Result	write (AsyncBufferView::ID bufferID, Function< void(AsyncBufferView::ID)> cb={})
	Writes a buffer (that must be allocated by the AsyncBuffersPool passed in AsyncWritableStream) When the buffer it will be actually written, AsyncWritableStream::eventWritten will be raised and its reference count will be decreased.
Result	write (AsyncBufferView &&bufferView, Function< void(AsyncBufferView::ID)> cb={})
	Push a new buffer view to the queue, registering it with the allocator.
void	end ()
	Ends the writable stream, waiting for all in-flight and queued writes to finish.
void	destroy ()
	Forcefully destroys the writable stream before calling end event releasing all resources.
AsyncBuffersPool &	getBuffersPool ()
	Obtains the buffers pool to access its data.
void	finishedWriting (AsyncBufferView::ID bufferID, Function< void(AsyncBufferView::ID)> &&cb, Result res)
	Signals that the given buffer (previously queued by write) has been fully written.
void	resumeWriting ()
	Resumes writing queued requests for this stream.
Result	unshift (AsyncBufferView::ID bufferID, Function< void(AsyncBufferView::ID)> &&cb)
	Puts back a buffer at the top of the write queue.
void	emitError (Result error)
	Signals an async error received.
void	tryAsync (Result potentialError)
	Will emit error if the passed in Result is false.
bool	isStillWriting () const
	Returns true if this stream is writing something.
bool	hasBeenDestroyed () const
	Returns true if the stream has been already destroyed (asynchronously through destroy())
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 >	eventDrain
	Emitted when an error occurs.
Event< MaxListeners >	eventFinish
	Emitted when write queue is empty.
Event< MaxListeners >	eventClose
	Emitted when no more data can be written.

Static Public Attributes
static constexpr int	MaxListeners = 8

Protected Member Functions
virtual Result	asyncWrite (AsyncBufferView::ID, Function< void(AsyncBufferView::ID)> func)=0
	Function that every stream must define to implement its custom write operation.
virtual bool	canEndWritable ()
	Allows keeping a writable in ENDING state until it has finished flushing all pending data.
virtual Result	asyncDestroyWritable ()
	Function that a writable stream can re-implement to release its internal resources.
void	finishedDestroyingWritable ()
	Function that MUST be called by re-implementations of asyncDestroyWritable once they're done.
void	stop ()

Detailed Description

Async destination abstraction where bytes can be written to.

When buffers are pushed faster than the stream can handle, they will get queued. Queuing process happens with a linked list stored in the AsyncBufferView itself. As AsyncBufferView contains a fixed (at init) number of buffers, the queue is bounded by the fact that user will be unable to allocate buffers to write until at least one will be made available again (i.e. a write finishes). User can listen to AsyncWritableStream::eventWritten to know when a buffer is written (and its refcount decreased) or AsyncWritableStream::eventDrain when the queue is empty.

Member Function Documentation

asyncDestroyWritable()

virtual Result SC::AsyncWritableStream::asyncDestroyWritable ( )

protectedvirtual

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

Note

The re-implementation MUST call finishedDestroyingWritable once it has finished destroying

Reimplemented in SC::AsyncRequestWritableStream< AsyncRequestType >, SC::AsyncRequestWritableStream< AsyncFileWrite >, and SC::AsyncRequestWritableStream< AsyncSocketSend >.

asyncWrite()

virtual Result SC::AsyncWritableStream::asyncWrite ( AsyncBufferView::ID , Function< void(AsyncBufferView::ID)> func )

protectedpure virtual

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

Implemented in SC::AsyncRequestWritableStream< AsyncRequestType >, SC::AsyncRequestWritableStream< AsyncFileWrite >, and SC::AsyncRequestWritableStream< AsyncSocketSend >.

canEndWritable()

virtual bool SC::AsyncWritableStream::canEndWritable ( )

protectedvirtual

Allows keeping a writable in ENDING state until it has finished flushing all pending data.

If a writable stream redefines this function it should return true to allow transitioning to ENDED state and return false to keep staying in ENDING state.

Reimplemented in SC::AsyncRequestWritableStream< AsyncRequestType >, SC::AsyncRequestWritableStream< AsyncFileWrite >, and SC::AsyncRequestWritableStream< AsyncSocketSend >.

destroy()

void SC::AsyncWritableStream::destroy

(

)

Forcefully destroys the writable 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::AsyncWritableStream::emitError

(

Result

error

)

Signals an async error received.

end()

void SC::AsyncWritableStream::end

(

)

Ends the writable stream, waiting for all in-flight and queued writes to finish.

After this happens, AsyncWritableStream::eventFinished will be raised

finishedDestroyingWritable()

void SC::AsyncWritableStream::finishedDestroyingWritable ( )

protected

Function that MUST be called by re-implementations of asyncDestroyWritable once they're done.

finishedWriting()

void SC::AsyncWritableStream::finishedWriting	(	AsyncBufferView::ID	bufferID,
		Function< void(AsyncBufferView::ID)> &&	cb,
		Result	res )

Signals that the given buffer (previously queued by write) has been fully written.

getAutoDestroy()

bool SC::AsyncWritableStream::getAutoDestroy ( ) const

inlinenodiscard

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

getBuffersPool()

AsyncBuffersPool & SC::AsyncWritableStream::getBuffersPool

(

)

Obtains the buffers pool to access its data.

getWriteQueueSize()

size_t SC::AsyncWritableStream::getWriteQueueSize ( ) const

inlinenodiscard

Returns the size of write queue.

hasBeenDestroyed()

bool SC::AsyncWritableStream::hasBeenDestroyed ( ) const

inlinenodiscard

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

init()

Result SC::AsyncWritableStream::init

(

AsyncBuffersPool &

buffersPool

)

Emitted when the underlying resource has been closed.

Inits the writable stream

Parameters

buffersPool

An instance of AsyncBuffersPool providing write buffers

Note

Remember to call AsyncWritableStream::setWriteQueue before calling init

isStillWriting()

bool SC::AsyncWritableStream::isStillWriting ( ) const

inlinenodiscard

Returns true if this stream is writing something.

resumeWriting()

void SC::AsyncWritableStream::resumeWriting

(

)

Resumes writing queued requests for this stream.

setAutoDestroy()

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

inline

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

setWriteQueue()

void SC::AsyncWritableStream::setWriteQueue ( Span< Request > requests )

inlineconstexpr

Sets the write queue for this writable stream.

tryAsync()

void SC::AsyncWritableStream::tryAsync

(

Result

potentialError

)

Will emit error if the passed in Result is false.

unshift()

Result SC::AsyncWritableStream::unshift	(	AsyncBufferView::ID	bufferID,
		Function< void(AsyncBufferView::ID)> &&	cb )

Puts back a buffer at the top of the write queue.

write() [1/2]

Result SC::AsyncWritableStream::write	(	AsyncBufferView &&	bufferView,
		Function< void(AsyncBufferView::ID)>	cb = {} )

Push a new buffer view to the queue, registering it with the allocator.

Returns

Invalid Result if write queue is full or if there are no available empty buffers slots in the pool

write() [2/2]

Result SC::AsyncWritableStream::write	(	AsyncBufferView::ID	bufferID,
		Function< void(AsyncBufferView::ID)>	cb = {} )

Writes a buffer (that must be allocated by the AsyncBuffersPool passed in AsyncWritableStream) When the buffer it will be actually written, AsyncWritableStream::eventWritten will be raised and its reference count will be decreased.

Parameters

bufferID	Buffer allocated from the associated AsyncBuffersPool (AsyncWritableStream::getBuffersPool)
cb	Callback that will be invoked when the write is finished

Returns

Invalid Result if write queue is full

Member Data Documentation

eventClose

Event<MaxListeners> SC::AsyncWritableStream::eventClose

Emitted when no more data can be written.

eventDrain

Event<MaxListeners> SC::AsyncWritableStream::eventDrain

Emitted when an error occurs.

eventFinish

Event<MaxListeners> SC::AsyncWritableStream::eventFinish

Emitted when write queue is empty.

---

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

• AsyncStreams.h