# Stream

<a id="stream"></a>

# Stream

```cpp
#include <icy/stream.h>

template<typename T>
class Stream
```

[Defined in src/base/include/icy/stream.h:30](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L30)

> **Inherits:** [`Handle< T >`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)

Basic stream type for sockets and pipes.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`Read`](#read-3) | `variable` | Declared here |
| [`Stream`](#stream-1) | `function` | Declared here |
| [`~Stream`](#stream-2) | `function` | Declared here |
| [`close`](#close-5) | `function` | Declared here |
| [`shutdown`](#shutdown) | `function` | Declared here |
| [`write`](#write-16) | `function` | Declared here |
| [`writeOwned`](#writeowned) | `function` | Declared here |
| [`setHighWaterMark`](#sethighwatermark) | `function` | Declared here |
| [`write`](#write-17) | `function` | Declared here |
| [`stream`](#stream-3) | `function` | Declared here |
| [`_buffer`](#_buffer-1) | `variable` | Declared here |
| [`_started`](#_started-1) | `variable` | Declared here |
| [`_highWaterMark`](#_highwatermark) | `variable` | Declared here |
| [`_writeReqFree`](#_writereqfree) | `variable` | Declared here |
| [`_ownedWriteReqFree`](#_ownedwritereqfree) | `variable` | Declared here |
| [`readStart`](#readstart-1) | `function` | Declared here |
| [`readStop`](#readstop) | `function` | Declared here |
| [`onRead`](#onread) | `function` | Declared here |
| [`allocWriteReq`](#allocwritereq) | `function` | Declared here |
| [`freeWriteReq`](#freewritereq) | `function` | Declared here |
| [`allocOwnedWriteReq`](#allocownedwritereq) | `function` | Declared here |
| [`freeOwnedWriteReq`](#freeownedwritereq) | `function` | Declared here |
| [`canQueueWrite`](#canqueuewrite) | `function` | Declared here |
| [`Handle`](#handle-1) | `typedef` | Declared here |
| [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-7) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`~Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-8) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`init`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#init-8) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`invoke`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#invoke) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`invokeOrThrow`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#invokeorthrow) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`close`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#close-18) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`ref`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#ref) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`unref`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#unref) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`initialized`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#initialized-1) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`active`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#active-3) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`closing`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#closing-1) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`closed`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#closed-2) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`error`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#error-11) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`setError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#seterror-1) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`setUVError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#setuverror) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`setAndThrowError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#setandthrowerror) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`throwLastError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#throwlasterror) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`loop`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#loop-3) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`reset`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#reset-12) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`get`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#get-15) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`tid`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#tid-2) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#context-5) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`rawPtr`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#rawptr) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`setCloseCleanup`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#setclosecleanup) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`clearCloseCleanup`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#clearclosecleanup) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`assertThread`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#assertthread) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`_loop`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_loop) | `variable` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`_context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_context-1) | `variable` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`_tid`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_tid) | `variable` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`_error`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_error-3) | `variable` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`onError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#onerror) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`onClose`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#onclose) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-9) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#operator-171) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-10) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#operator-172) | `function` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |
| [`Type`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#type-10) | `typedef` | Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) |

## Inherited from [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-7) `inline` | Construct the handle bound to the given event loop. |
| `function` | [`~Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-8) `virtual` `inline` |  |
| `function` | [`init`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#init-8) `inline` | Initialize the underlying libuv handle by calling `f` with the loop, the raw handle pointer, and any additional `args`. |
| `function` | [`invoke`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#invoke) `inline` | Invoke a libuv function `f` with `args` on the initialized handle. |
| `function` | [`invokeOrThrow`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#invokeorthrow) `inline` | Invoke a libuv function `f` with `args`, throwing on failure. |
| `function` | [`close`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#close-18) `virtual` `inline` | Close and destroy the handle. |
| `function` | [`ref`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#ref) `inline` | Re-reference the handle with the event loop after a previous [`unref()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#unref). |
| `function` | [`unref`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#unref) `inline` | Unreference the handle from the event loop. |
| `function` | [`initialized`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#initialized-1) `const` `inline` | Return `true` if the handle has been successfully initialized via [`init()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#init-8). |
| `function` | [`active`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#active-3) `virtual` `const` `inline` | Return `true` when the handle is active (libuv `uv_is_active`). |
| `function` | [`closing`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#closing-1) `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`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#closed-2) `virtual` `const` `inline` | Return `true` if the handle has been fully closed (context released). |
| `function` | [`error`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#error-11) `const` `inline` | Return the last error set on this handle, or a default-constructed [`Error`](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) if no error has occurred. |
| `function` | [`setError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#seterror-1) `virtual` `inline` | Set the error state and invoke [`onError()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#onerror). |
| `function` | [`setUVError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#setuverror) `inline` | Translate a libuv error code into an [`Error`](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) and call [`setError()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#seterror-1). |
| `function` | [`setAndThrowError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#setandthrowerror) `inline` | Set the error state from a libuv error code and throw a `std::runtime_error`. |
| `function` | [`throwLastError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#throwlasterror) `inline` | Throw a `std::runtime_error` if the handle currently holds an error. |
| `function` | [`loop`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#loop-3) `const` `inline` | Return the event loop this handle is bound to. |
| `function` | [`reset`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#reset-12) `inline` | Close the current handle (if open) and allocate a fresh [`Context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Context.md#context-2), leaving the handle ready to be re-initialized via [`init()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#init-8). |
| `function` | [`get`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#get-15) `const` `inline` | Return the raw libuv handle pointer cast to [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6). |
| `function` | [`tid`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#tid-2) `const` `inline` | Return the ID of the thread that constructed this handle. |
| `function` | [`context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#context-5) `const` `inline` | Return the raw [`Context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Context.md#context-2) that owns the libuv handle memory. |
| `function` | [`rawPtr`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#rawptr) `const` `inline` | Return the raw libuv handle pointer without retaining the [`Context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Context.md#context-2). |
| `function` | [`setCloseCleanup`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#setclosecleanup) `inline` |  |
| `function` | [`clearCloseCleanup`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#clearclosecleanup) `inline` |  |
| `function` | [`assertThread`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#assertthread) `const` `inline` | Throw `std::logic_error` if called from any thread other than the thread that constructed this handle. |
| `variable` | [`_loop`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_loop)  |  |
| `variable` | [`_context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_context-1)  |  |
| `variable` | [`_tid`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_tid)  |  |
| `variable` | [`_error`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#_error-3)  |  |
| `function` | [`onError`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#onerror) `virtual` `inline` | Called by [`setError()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#seterror-1) after the error state has been updated. |
| `function` | [`onClose`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#onclose) `virtual` `inline` | Called by [`close()`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#close-18) after the context has been released. |
| `function` | [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-9)  | NonCopyable and NonMovable. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#operator-171)  | Deleted assignment operator. |
| `function` | [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-10)  | Deleted constructor. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#operator-172)  | Deleted assignment operator. |
| `typedef` | [`Type`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#type-10)  | Define the native handle type. |

## Public Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`Signal`](https://auscaster.com/icey/docs/api-reference/icy-Signal.md#signal)< void(const char *, const int &)> | [`Read`](#read-3)  | Emitted when data has been received from the peer. |

---

<a id="read-3"></a>

### Read

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

Type: [`Signal`](https://auscaster.com/icey/docs/api-reference/icy-Signal.md#signal)< void(const char *, const int &)>

[Defined in src/base/include/icy/stream.h:211](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L211)

Emitted when data has been received from the peer.

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

## Public Methods

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

---

<a id="stream-1"></a>

### Stream

`inline`

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

[Defined in src/base/include/icy/stream.h:48](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L48)

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

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `loop` | [`uv::Loop`](https://auscaster.com/icey/docs/api-reference/uv.md#loop-1) * | Event loop to associate this stream with. |

---

<a id="stream-2"></a>

### ~Stream

`virtual` `inline`

```cpp
virtual inline ~Stream()
```

[Defined in src/base/include/icy/stream.h:55](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L55)

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

---

<a id="close-5"></a>

### close

`virtual` `inline` `override`

```cpp
virtual inline void close() override
```

[Defined in src/base/include/icy/stream.h:68](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L68)

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`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#close-18)

#### Reimplemented by

- [`SSLSocket::close`](https://auscaster.com/icey/docs/api-reference/icy-net-SSLSocket.md#close-21)
- [`TCPSocket::close`](https://auscaster.com/icey/docs/api-reference/icy-net-TCPSocket.md#close-22)

---

<a id="shutdown"></a>

### shutdown

`inline`

```cpp
inline bool shutdown()
```

[Defined in src/base/include/icy/stream.h:83](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L83)

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.

---

<a id="write-16"></a>

### write

`inline`

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

[Defined in src/base/include/icy/stream.h:106](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L106)

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. |

---

<a id="writeowned"></a>

### writeOwned

`inline`

```cpp
inline bool writeOwned(Buffer && buffer)
```

[Defined in src/base/include/icy/stream.h:141](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L141)

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`](https://auscaster.com/icey/docs/api-reference/base.md#buffer) && | Payload buffer moved into the async write request. |

---

<a id="sethighwatermark"></a>

### setHighWaterMark

`inline`

```cpp
inline void setHighWaterMark(size_t bytes)
```

[Defined in src/base/include/icy/stream.h:167](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L167)

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

---

<a id="write-17"></a>

### write

`inline`

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

[Defined in src/base/include/icy/stream.h:179](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L179)

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](#stream) handle to pass to the receiving process. |

---

<a id="stream-3"></a>

### stream

`inline`

```cpp
inline uv_stream_t * stream()
```

[Defined in src/base/include/icy/stream.h:203](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L203)

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`](https://auscaster.com/icey/docs/api-reference/base.md#buffer) | [`_buffer`](#_buffer-1)  |  |
| `bool` | [`_started`](#_started-1)  |  |
| `size_t` | [`_highWaterMark`](#_highwatermark)  | 16MB default write queue limit |
| `std::vector< uv_write_t * >` | [`_writeReqFree`](#_writereqfree)  | Freelist for write requests. |
| std::vector< [`OwnedWriteReq`](https://auscaster.com/icey/docs/api-reference/icy-Stream-OwnedWriteReq.md#ownedwritereq) * > | [`_ownedWriteReqFree`](#_ownedwritereqfree)  | Freelist for owned write requests. |

---

<a id="_buffer-1"></a>

### _buffer

```cpp
Buffer _buffer
```

Type: [`Buffer`](https://auscaster.com/icey/docs/api-reference/base.md#buffer)

[Defined in src/base/include/icy/stream.h:375](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L375)

---

<a id="_started-1"></a>

### _started

```cpp
bool _started {false}
```

[Defined in src/base/include/icy/stream.h:376](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L376)

---

<a id="_highwatermark"></a>

### _highWaterMark

```cpp
size_t _highWaterMark {16 * 1024 * 1024}
```

[Defined in src/base/include/icy/stream.h:377](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L377)

16MB default write queue limit

---

<a id="_writereqfree"></a>

### _writeReqFree

```cpp
std::vector< uv_write_t * > _writeReqFree
```

[Defined in src/base/include/icy/stream.h:378](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L378)

Freelist for write requests.

---

<a id="_ownedwritereqfree"></a>

### _ownedWriteReqFree

```cpp
std::vector< OwnedWriteReq * > _ownedWriteReqFree
```

Type: std::vector< [`OwnedWriteReq`](https://auscaster.com/icey/docs/api-reference/icy-Stream-OwnedWriteReq.md#ownedwritereq) * >

[Defined in src/base/include/icy/stream.h:379](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L379)

Freelist for owned write requests.

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `bool` | [`readStart`](#readstart-1) `virtual` `inline` | Begin reading from the stream by registering libuv read callbacks. |
| `bool` | [`readStop`](#readstop) `virtual` `inline` | Stop reading from the stream. |
| `void` | [`onRead`](#onread) `virtual` `inline` | Called by `handleRead` when `len` bytes of `data` arrive. |
| `uv_write_t *` | [`allocWriteReq`](#allocwritereq) `inline` | Return a `uv_write_t` from the freelist, or allocate a new one if the pool is empty. |
| `void` | [`freeWriteReq`](#freewritereq) `inline` | Return `req` to the freelist, or delete it if the pool is at capacity. |
| [`OwnedWriteReq`](https://auscaster.com/icey/docs/api-reference/icy-Stream-OwnedWriteReq.md#ownedwritereq) * | [`allocOwnedWriteReq`](#allocownedwritereq) `inline` |  |
| `void` | [`freeOwnedWriteReq`](#freeownedwritereq) `inline` |  |
| `bool` | [`canQueueWrite`](#canqueuewrite) `inline` |  |

---

<a id="readstart-1"></a>

### readStart

`virtual` `inline`

```cpp
virtual inline bool readStart()
```

[Defined in src/base/include/icy/stream.h:220](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L220)

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`](https://auscaster.com/icey/docs/api-reference/icy-Pipe.md#readstart)

---

<a id="readstop"></a>

### readStop

`virtual` `inline`

```cpp
virtual inline bool readStop()
```

[Defined in src/base/include/icy/stream.h:237](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L237)

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.

---

<a id="onread"></a>

### onRead

`virtual` `inline`

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

[Defined in src/base/include/icy/stream.h:254](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L254)

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

- [`SSLSocket::onRead`](https://auscaster.com/icey/docs/api-reference/icy-net-SSLSocket.md#onread-1)
- [`TCPSocket::onRead`](https://auscaster.com/icey/docs/api-reference/icy-net-TCPSocket.md#onread-2)

#### 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`. |

---

<a id="allocwritereq"></a>

### allocWriteReq

`inline`

```cpp
inline uv_write_t * allocWriteReq()
```

[Defined in src/base/include/icy/stream.h:319](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L319)

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

---

<a id="freewritereq"></a>

### freeWriteReq

`inline`

```cpp
inline void freeWriteReq(uv_write_t * req)
```

[Defined in src/base/include/icy/stream.h:332](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L332)

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. |

---

<a id="allocownedwritereq"></a>

### allocOwnedWriteReq

`inline`

```cpp
inline OwnedWriteReq * allocOwnedWriteReq()
```

[Defined in src/base/include/icy/stream.h:341](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L341)

---

<a id="freeownedwritereq"></a>

### freeOwnedWriteReq

`inline`

```cpp
inline void freeOwnedWriteReq(OwnedWriteReq * req)
```

[Defined in src/base/include/icy/stream.h:351](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L351)

---

<a id="canqueuewrite"></a>

### canQueueWrite

`inline`

```cpp
inline bool canQueueWrite(size_t len)
```

[Defined in src/base/include/icy/stream.h:362](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L362)

## Public Types

| Name | Description |
|------|-------------|
| [`Handle`](#handle-1)  |  |

---

<a id="handle-1"></a>

### Handle

```cpp
using Handle = uv::Handle< T >
```

Type: [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< T >

[Defined in src/base/include/icy/stream.h:33](https://github.com/auscaster/icey/blob/main/src/base/include/icy/stream.h#L33)