Base module

Stream

Basic stream type for sockets and pipes.

Stream

#include <icy/stream.h>

Inherits: Handle< T >

Basic stream type for sockets and pipes.

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

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`	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)

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()

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

close

virtual inline

virtual inline void close()

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.

shutdown

inline

inline bool shutdown()

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)

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)

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)

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)

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()

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

_started

bool _started {false}

_highWaterMark

size_t _highWaterMark {16 * 1024 * 1024}

16MB default write queue limit

_writeReqFree

std::vector< uv_write_t * > _writeReqFree

Freelist for write requests.

_ownedWriteReqFree

std::vector< OwnedWriteReq * > _ownedWriteReqFree

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()

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.

readStop

virtual inline

virtual inline bool readStop()

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)

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.

allocWriteReq

inline

inline uv_write_t * allocWriteReq()

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)

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()

freeOwnedWriteReq

inline

inline void freeOwnedWriteReq(OwnedWriteReq * req)

canQueueWrite

inline

inline bool canQueueWrite(size_t len)

Public Types

Name	Description
`Handle`

Handle

uv::Handle< T > Handle()

Built with