Stream

#include <icy/stream.h>

template<typename T>
class Stream

Defined in src/base/include/icy/stream.h:30

Inherits: Handle< T >

List of all members

Name	Kind	Owner
`Read`	`variable`	Declared here
`Stream`	`function`	Declared here
`~Stream`	`function`	Declared here
`close`	`function`	Declared here
`shutdown`	`function`	Declared here
`write`	`function`	Declared here
`writeOwned`	`function`	Declared here
`setHighWaterMark`	`function`	Declared here
`write`	`function`	Declared here
`stream`	`function`	Declared here
`_buffer`	`variable`	Declared here
`_started`	`variable`	Declared here
`_highWaterMark`	`variable`	Declared here
`_writeReqFree`	`variable`	Declared here
`_ownedWriteReqFree`	`variable`	Declared here
`readStart`	`function`	Declared here
`readStop`	`function`	Declared here
`onRead`	`function`	Declared here
`allocWriteReq`	`function`	Declared here
`freeWriteReq`	`function`	Declared here
`allocOwnedWriteReq`	`function`	Declared here
`freeOwnedWriteReq`	`function`	Declared here
`canQueueWrite`	`function`	Declared here
`Handle`	`typedef`	Declared here
`Handle`	`function`	Inherited from `Handle`
`~Handle`	`function`	Inherited from `Handle`
`init`	`function`	Inherited from `Handle`
`invoke`	`function`	Inherited from `Handle`
`invokeOrThrow`	`function`	Inherited from `Handle`
`close`	`function`	Inherited from `Handle`
`ref`	`function`	Inherited from `Handle`
`unref`	`function`	Inherited from `Handle`
`initialized`	`function`	Inherited from `Handle`
`active`	`function`	Inherited from `Handle`
`closing`	`function`	Inherited from `Handle`
`closed`	`function`	Inherited from `Handle`
`error`	`function`	Inherited from `Handle`
`setError`	`function`	Inherited from `Handle`
`setUVError`	`function`	Inherited from `Handle`
`setAndThrowError`	`function`	Inherited from `Handle`
`throwLastError`	`function`	Inherited from `Handle`
`loop`	`function`	Inherited from `Handle`
`reset`	`function`	Inherited from `Handle`
`get`	`function`	Inherited from `Handle`
`tid`	`function`	Inherited from `Handle`
`context`	`function`	Inherited from `Handle`
`rawPtr`	`function`	Inherited from `Handle`
`setCloseCleanup`	`function`	Inherited from `Handle`
`clearCloseCleanup`	`function`	Inherited from `Handle`
`assertThread`	`function`	Inherited from `Handle`
`_loop`	`variable`	Inherited from `Handle`
`_context`	`variable`	Inherited from `Handle`
`_tid`	`variable`	Inherited from `Handle`
`_error`	`variable`	Inherited from `Handle`
`onError`	`function`	Inherited from `Handle`
`onClose`	`function`	Inherited from `Handle`
`Handle`	`function`	Inherited from `Handle`
`operator=`	`function`	Inherited from `Handle`
`Handle`	`function`	Inherited from `Handle`
`operator=`	`function`	Inherited from `Handle`
`Type`	`typedef`	Inherited from `Handle`

Inherited from `Handle`

Kind	Name	Description
`function`	`Handle` inline	Construct the handle bound to the given event loop.
`function`	`~Handle` virtual inline
`function`	`init` inline	Initialize the underlying libuv handle by calling `f` with the loop, the raw handle pointer, and any additional `args`.
`function`	`invoke` inline	Invoke a libuv function `f` with `args` on the initialized handle.
`function`	`invokeOrThrow` inline	Invoke a libuv function `f` with `args`, throwing on failure.
`function`	`close` virtual inline	Close and destroy the handle.
`function`	`ref` inline	Re-reference the handle with the event loop after a previous `unref()`.
`function`	`unref` inline	Unreference the handle from the event loop.
`function`	`initialized` const inline	Return `true` if the handle has been successfully initialized via `init()`.
`function`	`active` virtual const inline	Return `true` when the handle is active (libuv `uv_is_active`).
`function`	`closing` virtual const inline	Return `true` if `uv_close` has been called and the handle is awaiting its close callback (libuv `uv_is_closing`).
`function`	`closed` virtual const inline	Return `true` if the handle has been fully closed (context released).
`function`	`error` const inline	Return the last error set on this handle, or a default-constructed `Error` if no error has occurred.
`function`	`setError` virtual inline	Set the error state and invoke `onError()`.
`function`	`setUVError` inline	Translate a libuv error code into an `Error` and call `setError()`.
`function`	`setAndThrowError` inline	Set the error state from a libuv error code and throw a `std::runtime_error`.
`function`	`throwLastError` inline	Throw a `std::runtime_error` if the handle currently holds an error.
`function`	`loop` const inline	Return the event loop this handle is bound to.
`function`	`reset` inline	Close the current handle (if open) and allocate a fresh `Context`, leaving the handle ready to be re-initialized via `init()`.
`function`	`get` const inline	Return the raw libuv handle pointer cast to `Handle`.
`function`	`tid` const inline	Return the ID of the thread that constructed this handle.
`function`	`context` const inline	Return the raw `Context` that owns the libuv handle memory.
`function`	`rawPtr` const inline	Return the raw libuv handle pointer without retaining the `Context`.
`function`	`setCloseCleanup` inline
`function`	`clearCloseCleanup` inline
`function`	`assertThread` const inline	Throw `std::logic_error` if called from any thread other than the thread that constructed this handle.
`variable`	`_loop`
`variable`	`_context`
`variable`	`_tid`
`variable`	`_error`
`function`	`onError` virtual inline	Called by `setError()` after the error state has been updated.
`function`	`onClose` virtual inline	Called by `close()` after the context has been released.
`function`	`Handle`	NonCopyable and NonMovable.
`function`	`operator=`	Deleted assignment operator.
`function`	`Handle`	Deleted constructor.
`function`	`operator=`	Deleted assignment operator.
`typedef`	`Type`	Define the native handle type.

Public Attributes

Return	Name	Description
`Signal`< void(const char *, const int &)>	`Read`	Emitted when data has been received from the peer.

Read

Signal< void(const char *, const int &)> Read

Type: Signal< void(const char *, const int &)>

Defined in src/base/include/icy/stream.h:211

Emitted when data has been received from the peer.

Slot signature: void(const char* data, const int& len)

Public Methods

Return	Name	Description
	`Stream` inline	Construct the stream bound to `loop` with a 64 KiB read buffer.
	`~Stream` virtual inline	Destroy the stream, stopping reads and freeing pooled write requests.
`void`	`close` virtual inline override	Closes and resets the stream handle. This will close the active socket/pipe and destroy the handle.
`bool`	`shutdown` inline	Send a TCP/pipe shutdown request to the connected peer.
`bool`	`write` inline	Write `len` bytes from `data` to the stream.
`bool`	`writeOwned` inline	Write an owned payload buffer to the stream.
`void`	`setHighWaterMark` inline	Set the high water mark for the write queue (default 16MB). When the write queue exceeds this size, write() returns false.
`bool`	`write` inline	Write `len` bytes from `data` together with a stream handle over an IPC pipe (uses `uv_write2`).
`uv_stream_t *`	`stream` inline	Return the underlying `uv_stream_t` pointer cast from the native handle.

inline

inline Stream(uv::Loop * loop = uv::defaultLoop())

Defined in src/base/include/icy/stream.h:48

Construct the stream bound to loop with a 64 KiB read buffer.

Parameters

Parameter	Type	Description
`loop`	`uv::Loop` *	Event loop to associate this stream with.

~Stream

virtual inline

virtual inline ~Stream()

Defined in src/base/include/icy/stream.h:55

Destroy the stream, stopping reads and freeing pooled write requests.

close

virtual inline override

virtual inline void close() override

Defined in src/base/include/icy/stream.h:68

Closes and resets the stream handle. This will close the active socket/pipe and destroy the handle.

If the stream is already closed this call will have no side-effects.

Reimplements

Handle::close

Reimplemented by

shutdown

inline

inline bool shutdown()

Defined in src/base/include/icy/stream.h:83

Send a TCP/pipe shutdown request to the connected peer.

Issues a half-close: no further writes will be accepted after this, but the stream remains open for reading until the peer also closes.

Returns

true if the shutdown request was submitted successfully; false if the stream is not active.

write

inline

inline bool write(const char * data, size_t len)

Defined in src/base/include/icy/stream.h:106

Write len bytes from data to the stream.

The write is non-blocking; data is buffered by libuv. Returns false without throwing if the stream is inactive, reads have not started, or the internal write queue exceeds the high-water mark.

Returns

true if the write was queued; false on backpressure or if the stream is not in a writable state.

Parameters

Parameter	Type	Description
`data`	`const char *`	Pointer to the bytes to send. Must remain valid until the write completion callback fires.
`len`	`size_t`	Number of bytes to send.

writeOwned

inline

inline bool writeOwned(Buffer && buffer)

Defined in src/base/include/icy/stream.h:141

Write an owned payload buffer to the stream.

The buffer is moved into the queued write request and retained until the libuv completion callback fires. Use this path whenever the caller does not naturally own storage beyond the current stack frame.

Returns

true if the write was queued; false on backpressure or if the stream is not in a writable state.

Parameters

Parameter	Type	Description
`buffer`	`Buffer` &&	Payload buffer moved into the async write request.

setHighWaterMark

inline

inline void setHighWaterMark(size_t bytes)

Defined in src/base/include/icy/stream.h:167

Set the high water mark for the write queue (default 16MB). When the write queue exceeds this size, write() returns false.

write

inline

inline bool write(const char * data, size_t len, uv_stream_t * send)

Defined in src/base/include/icy/stream.h:179

Write len bytes from data together with a stream handle over an IPC pipe (uses uv_write2).

Only valid for named-pipe handles opened with IPC mode enabled. Throws std::logic_error if called on a non-IPC pipe.

Returns

true if the write was queued; false on error.

Parameters

Parameter	Type	Description
`data`	`const char *`	Bytes to send alongside the handle.
`len`	`size_t`	Number of bytes to send.
`send`	`uv_stream_t *`	Stream handle to pass to the receiving process.

stream

inline

inline uv_stream_t * stream()

Defined in src/base/include/icy/stream.h:203

Return the underlying uv_stream_t pointer cast from the native handle.

Returns

Pointer to the uv_stream_t, or nullptr if the handle is closed.

Protected Attributes

Return	Name	Description
`Buffer`	`_buffer`
`bool`	`_started`
`size_t`	`_highWaterMark`	16MB default write queue limit
`std::vector< uv_write_t * >`	`_writeReqFree`	Freelist for write requests.
std::vector< `OwnedWriteReq` * >	`_ownedWriteReqFree`	Freelist for owned write requests.

_buffer

Buffer _buffer

Type: Buffer

Defined in src/base/include/icy/stream.h:375

_started

bool _started {false}

Defined in src/base/include/icy/stream.h:376

_highWaterMark

size_t _highWaterMark {16 * 1024 * 1024}

Defined in src/base/include/icy/stream.h:377

16MB default write queue limit

_writeReqFree

std::vector< uv_write_t * > _writeReqFree

Defined in src/base/include/icy/stream.h:378

Freelist for write requests.

_ownedWriteReqFree

std::vector< OwnedWriteReq * > _ownedWriteReqFree

Type: std::vector< OwnedWriteReq * >

Defined in src/base/include/icy/stream.h:379

Freelist for owned write requests.

Protected Methods

Return	Name	Description
`bool`	`readStart` virtual inline	Begin reading from the stream by registering libuv read callbacks.
`bool`	`readStop` virtual inline	Stop reading from the stream.
`void`	`onRead` virtual inline	Called by `handleRead` when `len` bytes of `data` arrive.
`uv_write_t *`	`allocWriteReq` inline	Return a `uv_write_t` from the freelist, or allocate a new one if the pool is empty.
`void`	`freeWriteReq` inline	Return `req` to the freelist, or delete it if the pool is at capacity.
`OwnedWriteReq` *	`allocOwnedWriteReq` inline
`void`	`freeOwnedWriteReq` inline
`bool`	`canQueueWrite` inline

readStart

virtual inline

virtual inline bool readStart()

Defined in src/base/include/icy/stream.h:220

Begin reading from the stream by registering libuv read callbacks.

Sets the stream's data pointer to this so callbacks can recover the C++ object. Has no effect and returns false if already started.

Returns

true if uv_read_start was called successfully.

Reimplemented by

Pipe::readStart

readStop

virtual inline

virtual inline bool readStop()

Defined in src/base/include/icy/stream.h:237

Stop reading from the stream.

No further read callbacks will fire after this returns. Has no effect and returns false if not currently started.

Returns

true if uv_read_stop was called successfully.

onRead

virtual inline

virtual inline void onRead(const char * data, size_t len)

Defined in src/base/include/icy/stream.h:254

Called by handleRead when len bytes of data arrive.

The default implementation emits the Read signal. Override to intercept data before it reaches signal subscribers.

Reimplemented by

Parameters

Parameter	Type	Description
`data`	`const char *`	Pointer into the read buffer; valid only for this call.
`len`	`size_t`	Number of valid bytes in `data`.

allocWriteReq

inline

inline uv_write_t * allocWriteReq()

Defined in src/base/include/icy/stream.h:319

Return a uv_write_t from the freelist, or allocate a new one if the pool is empty.

Returns

Pointer to an unused uv_write_t.

freeWriteReq

inline

inline void freeWriteReq(uv_write_t * req)

Defined in src/base/include/icy/stream.h:332

Return req to the freelist, or delete it if the pool is at capacity.

Parameters

Parameter	Type	Description
`req`	`uv_write_t *`	Write request to recycle or free.

allocOwnedWriteReq

inline

inline OwnedWriteReq * allocOwnedWriteReq()

Defined in src/base/include/icy/stream.h:341

freeOwnedWriteReq

inline

inline void freeOwnedWriteReq(OwnedWriteReq * req)

Defined in src/base/include/icy/stream.h:351

canQueueWrite

inline

inline bool canQueueWrite(size_t len)

Defined in src/base/include/icy/stream.h:362

Public Types

Name	Description
`Handle`

Handle

using Handle = uv::Handle< T >

Type: uv::Handle< T >

Defined in src/base/include/icy/stream.h:33

List of all members

Inherited from Handle

Public Attributes

Read

Public Methods

Stream

Parameters

~Stream

close

Reimplements

Reimplemented by

shutdown

Returns

write

Returns

Parameters

writeOwned

Returns

Parameters

setHighWaterMark

write

Returns

Parameters

stream

Returns

Protected Attributes

_buffer

_started

_highWaterMark

_writeReqFree

_ownedWriteReqFree

Protected Methods

readStart

Returns

Reimplemented by

readStop

Returns

onRead

Reimplemented by

Parameters

allocWriteReq

Returns

freeWriteReq

Parameters

allocOwnedWriteReq

freeOwnedWriteReq

canQueueWrite

Public Types

Handle

Inherited from `Handle`