Stream

#include <icy/stream.h>

template<typename T>
class Stream

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

Inherits: Handle< T >

Basic stream type for sockets and pipes.

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`
`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()](icy-uv-Handle.html#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()](icy-uv-Handle.html#init-8)`.
`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](icy-Error.html#error)` if no error has occurred.
`function`	`setError` `virtual` `inline`	Set the error state and invoke `[onError()](icy-uv-Handle.html#onerror)`.
`function`	`setUVError` `inline`	Translate a libuv error code into an `[Error](icy-Error.html#error)` and call `[setError()](icy-uv-Handle.html#seterror-1)`.
`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](icy-uv-Context.html#context-2)`, leaving the handle ready to be re-initialized via `[init()](icy-uv-Handle.html#init-8)`.
`function`	`get` `const` `inline`	Return the raw libuv handle pointer cast to `[Handle](icy-uv-Handle.html#handle-6)`.
`function`	`tid` `const` `inline`	Return the ID of the thread that constructed this handle.
`function`	`context` `const` `inline`	Return the raw `[Context](icy-uv-Context.html#context-2)` that owns the libuv handle memory.
`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()](icy-uv-Handle.html#seterror-1)` after the error state has been updated.
`function`	`onClose` `virtual` `inline`	Called by `[close()](icy-uv-Handle.html#close-18)` 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

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

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.

Stream

inline

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

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

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

Parameters

loop Event loop to associate this stream with.

~Stream

virtual inline

virtual inline ~Stream()

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

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:67

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

close

Reimplemented by

shutdown

inline

inline bool shutdown()

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

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:105

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.

Parameters

data Pointer to the bytes to send. Must remain valid until the write completion callback fires.
len Number of bytes to send.

Returns

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

writeOwned

inline

inline bool writeOwned(Buffer && buffer)

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

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.

Parameters

buffer Payload buffer moved into the async write request.

Returns

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

setHighWaterMark

inline

inline void setHighWaterMark(size_t bytes)

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

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:178

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.

Parameters

data Bytes to send alongside the handle.
len Number of bytes to send.
send Stream handle to pass to the receiving process.

Returns

true if the write was queued; false on error.

stream

inline

inline uv_stream_t * stream()

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

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

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

_started

bool _started {false}

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

_highWaterMark

size_t _highWaterMark {16 * 1024 * 1024}

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

16MB default write queue limit

_writeReqFree

std::vector< uv_write_t * > _writeReqFree

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

Freelist for write requests.

_ownedWriteReqFree

std::vector< OwnedWriteReq * > _ownedWriteReqFree

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

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:219

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

readStart

readStop

virtual inline

virtual inline bool readStop()

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

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:253

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.

Parameters

data Pointer into the read buffer; valid only for this call.
len Number of valid bytes in data.

Reimplemented by

allocWriteReq

inline

inline uv_write_t * allocWriteReq()

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

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:331

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

Parameters

req Write request to recycle or free.

allocOwnedWriteReq

inline

inline OwnedWriteReq * allocOwnedWriteReq()

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

freeOwnedWriteReq

inline

inline void freeOwnedWriteReq(OwnedWriteReq * req)

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

canQueueWrite

inline

inline bool canQueueWrite(size_t len)

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

Public Types

Name	Description
`Handle`

Handle

using Handle = uv::Handle< T >

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

Stream

List of all members

Inherited from Handle

Public Attributes

Read

Public Methods

Stream

Parameters

~Stream

close

Reimplements

Reimplemented by

shutdown

Returns

write

Parameters

Returns

writeOwned

Parameters

Returns

setHighWaterMark

write

Parameters

Returns

stream

Returns

Protected Attributes

_buffer

_started

_highWaterMark

_writeReqFree

_ownedWriteReqFree

Protected Methods

readStart

Returns

Reimplemented by

readStop

Returns

onRead

Parameters

Reimplemented by

allocWriteReq

Returns

freeWriteReq

Parameters

allocOwnedWriteReq

freeOwnedWriteReq

canQueueWrite

Public Types

Handle

Inherited from `Handle`