# ThreadedStreamReader

<a id="threadedstreamreader"></a>

# ThreadedStreamReader

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

class ThreadedStreamReader
```

[Defined in src/base/include/icy/packetio.h:31](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L31)

> **Inherits:** [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter), [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable)

Threaded stream reader class.

This class can be connected to a [`PacketStream`](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) to read input from any class that derives from `std::istream`. It's most regularly used for reading input files.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`emitter`](#emitter-4) | `variable` | Declared here |
| [`ThreadedStreamReader`](#threadedstreamreader-1) | `function` | Declared here |
| [`~ThreadedStreamReader`](#threadedstreamreader-2) | `function` | Declared here |
| [`start`](#start-10) | `function` | Declared here |
| [`stop`](#stop-3) | `function` | Declared here |
| [`stream`](#stream-6) | `function` | Declared here |
| [`stream`](#stream-7) | `function` | Declared here |
| [`_runner`](#_runner-1) | `variable` | Declared here |
| [`_istream`](#_istream) | `variable` | Declared here |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter) | `variable` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`start`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#start-21) | `function` | Inherited from [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable) |
| [`stop`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#stop-12) | `function` | Inherited from [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable) |

## Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1)  | Construct the adapter, binding it to the given packet signal. |
| `function` | [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) `virtual` `inline` |  |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) `virtual` | Emit a mutable raw buffer as a packet. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) `virtual` | Emit a read-only raw buffer as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) `virtual` | Emit a string as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) `virtual` | Emit a flag-only packet carrying no payload data. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) `virtual` | Emit an existing packet directly onto the outgoing signal. |
| `function` | [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter)  | Returns a reference to the outgoing packet signal. |
| `function` | [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) `virtual` `const` | Returns how this adapter treats incoming packet lifetime. Most adapters are synchronous and therefore only borrow the packet for the current call chain. Queue-style adapters override this to advertise that they clone before deferred use. Callers may treat the first adapter reporting Cloned or Retained as the explicit ownership boundary in the stream graph. |
| `function` | [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) `virtual` `inline` | Called by the [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) to notify when the internal [Stream](https://auscaster.com/icey/docs/api-reference/icy-Stream.md#stream) state changes. On receiving the Stopped state, it is the responsibility of the adapter to have ceased all outgoing packet transmission, especially in multi-thread scenarios. |
| `variable` | [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter)  |  |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3)  | NonCopyable and NonMovable. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72)  | Deleted assignment operator. |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4)  | Deleted constructor. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73)  | Deleted assignment operator. |

## Inherited from [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`start`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#start-21) `virtual` | Starts the object (e.g. begins processing or listening). |
| `function` | [`stop`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#stop-12) `virtual` | Stops the object (e.g. halts processing or closes resources). |

## Public Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) | [`emitter`](#emitter-4)  |  |

---

<a id="emitter-4"></a>

### emitter

```cpp
PacketSignal emitter
```

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

[Defined in src/base/include/icy/packetio.h:93](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L93)

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`ThreadedStreamReader`](#threadedstreamreader-1) `inline` |  |
|  | [`~ThreadedStreamReader`](#threadedstreamreader-2) `inline` | Stops the reader thread and deletes the owned stream. |
| `void` | [`start`](#start-10) `virtual` `inline` `override` | Starts the reader thread; emits one line per iteration as a [RawPacket](https://auscaster.com/icey/docs/api-reference/icy-RawPacket.md#rawpacket-4). Emits a [FlagPacket](https://auscaster.com/icey/docs/api-reference/icy-FlagPacket.md#flagpacket) with [`PacketFlags::Final`](https://auscaster.com/icey/docs/api-reference/base.md#packetflags) on EOF. |
| `void` | [`stop`](#stop-3) `virtual` `inline` `override` | Cancels the reader thread. |
| `StreamT &` | [`stream`](#stream-6) `inline` | Returns the internal stream cast to `StreamT`. |
| `std::istream &` | [`stream`](#stream-7) `inline` |  |

---

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

### ThreadedStreamReader

`inline`

```cpp
inline ThreadedStreamReader(std::istream * is)
```

[Defined in src/base/include/icy/packetio.h:36](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L36)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `is` | `std::istream *` | Input stream to read from; takes ownership. |

---

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

### ~ThreadedStreamReader

`inline`

```cpp
inline ~ThreadedStreamReader()
```

[Defined in src/base/include/icy/packetio.h:44](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L44)

Stops the reader thread and deletes the owned stream.

---

<a id="start-10"></a>

### start

`virtual` `inline` `override`

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

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

Starts the reader thread; emits one line per iteration as a [RawPacket](https://auscaster.com/icey/docs/api-reference/icy-RawPacket.md#rawpacket-4). Emits a [FlagPacket](https://auscaster.com/icey/docs/api-reference/icy-FlagPacket.md#flagpacket) with [`PacketFlags::Final`](https://auscaster.com/icey/docs/api-reference/base.md#packetflags) on EOF.

#### Reimplements

- [`Startable::start`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#start-21)

---

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

### stop

`virtual` `inline` `override`

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

[Defined in src/base/include/icy/packetio.h:71](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L71)

Cancels the reader thread.

#### Reimplements

- [`Startable::stop`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#stop-12)

---

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

### stream

`inline`

```cpp
template<class StreamT> inline StreamT & stream()
```

[Defined in src/base/include/icy/packetio.h:81](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L81)

Returns the internal stream cast to `StreamT`. 
#### Returns
Reference to the cast stream.

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the cast fails. |

---

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

### stream

`inline`

```cpp
inline std::istream & stream()
```

[Defined in src/base/include/icy/packetio.h:91](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L91)

#### Returns
Reference to the underlying input stream.

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`Thread`](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1) | [`_runner`](#_runner-1)  |  |
| `std::istream *` | [`_istream`](#_istream)  |  |

---

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

### _runner

```cpp
Thread _runner
```

Type: [`Thread`](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1)

[Defined in src/base/include/icy/packetio.h:96](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L96)

---

<a id="_istream"></a>

### _istream

```cpp
std::istream * _istream
```

[Defined in src/base/include/icy/packetio.h:97](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetio.h#L97)