# PacketStream # PacketStream ```cpp #include class PacketStream ``` [Defined in src/base/include/icy/packetstream.h:308](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L308) > **Inherits:** [`Stateful< PacketStreamState >`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) Processes and broadcasts IPackets through a configurable adapter graph. A [PacketStream](#packetstream) consists of one or many PacketSources, one or many PacketProcessors, and one or many delegate receivers. This class enables the developer to setup a processor chain in order to perform arbitrary processing on data packets using interchangeable packet adapters, and pump the output to any delegate function or even another [PacketStream](#packetstream). Note that [PacketStream](#packetstream) itself inherits from [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter), so a [PacketStream](#packetstream) can be the source of another [PacketStream](#packetstream). All [PacketStream](#packetstream) methods are thread-safe, but once the stream is running you will not be able to attach or detach stream adapters. In order to synchronize output packets with the application event loop take a look at the [SyncPacketQueue](https://auscaster.com/icey/docs/api-reference/icy-SyncPacketQueue.md#syncpacketqueue) class. For lengthy operations you can add an [AsyncPacketQueue](https://auscaster.com/icey/docs/api-reference/icy-AsyncPacketQueue.md#asyncpacketqueue) to the start of the stream to defer processing from the PacketSource thread. ## List of all members | Name | Kind | Owner | |------|------|-------| | [`emitter`](#emitter-1) | `variable` | Declared here | | [`Error`](#error-4) | `variable` | Declared here | | [`Close`](#close-2) | `variable` | Declared here | | [`PacketStream`](#packetstream-1) | `function` | Declared here | | [`~PacketStream`](#packetstream-2) | `function` | Declared here | | [`PacketStream`](#packetstream-3) | `function` | Declared here | | [`operator=`](#operator-70) | `function` | Declared here | | [`PacketStream`](#packetstream-4) | `function` | Declared here | | [`operator=`](#operator-71) | `function` | Declared here | | [`start`](#start-2) | `function` | Declared here | | [`stop`](#stop-1) | `function` | Declared here | | [`pause`](#pause-1) | `function` | Declared here | | [`resume`](#resume) | `function` | Declared here | | [`close`](#close-3) | `function` | Declared here | | [`reset`](#reset-5) | `function` | Declared here | | [`active`](#active) | `function` | Declared here | | [`stopped`](#stopped) | `function` | Declared here | | [`closed`](#closed) | `function` | Declared here | | [`lock`](#lock-1) | `function` | Declared here | | [`locked`](#locked) | `function` | Declared here | | [`write`](#write-11) | `function` | Declared here | | [`write`](#write-12) | `function` | Declared here | | [`write`](#write-13) | `function` | Declared here | | [`attachSource`](#attachsource) | `function` | Declared here | | [`attachSource`](#attachsource-1) | `function` | Declared here | | [`attachSource`](#attachsource-2) | `function` | Declared here | | [`detachSource`](#detachsource) | `function` | Declared here | | [`detachSource`](#detachsource-1) | `function` | Declared here | | [`attach`](#attach) | `function` | Declared here | | [`attach`](#attach-1) | `function` | Declared here | | [`detach`](#detach-1) | `function` | Declared here | | [`synchronizeOutput`](#synchronizeoutput) | `function` | Declared here | | [`autoStart`](#autostart) | `function` | Declared here | | [`closeOnError`](#closeonerror) | `function` | Declared here | | [`error`](#error-5) | `function` | Declared here | | [`name`](#name-2) | `function` | Declared here | | [`adapters`](#adapters) | `function` | Declared here | | [`sources`](#sources) | `function` | Declared here | | [`processors`](#processors) | `function` | Declared here | | [`numSources`](#numsources) | `function` | Declared here | | [`numProcessors`](#numprocessors) | `function` | Declared here | | [`numAdapters`](#numadapters) | `function` | Declared here | | [`getSource`](#getsource) | `function` | Declared here | | [`getProcessor`](#getprocessor) | `function` | Declared here | | [`getProcessor`](#getprocessor-1) | `function` | Declared here | | [`_mutex`](#_mutex-3) | `variable` | Declared here | | [`_procMutex`](#_procmutex) | `variable` | Declared here | | [`_procMutexOwner`](#_procmutexowner) | `variable` | Declared here | | [`_name`](#_name-1) | `variable` | Declared here | | [`_sources`](#_sources) | `variable` | Declared here | | [`_processors`](#_processors) | `variable` | Declared here | | [`_states`](#_states) | `variable` | Declared here | | [`_error`](#_error) | `variable` | Declared here | | [`_autoStart`](#_autostart) | `variable` | Declared here | | [`_closeOnError`](#_closeonerror) | `variable` | Declared here | | [`_wired`](#_wired) | `variable` | Declared here | | [`setup`](#setup) | `function` | Declared here | | [`teardown`](#teardown) | `function` | Declared here | | [`attachSource`](#attachsource-3) | `function` | Declared here | | [`attach`](#attach-2) | `function` | Declared here | | [`startSources`](#startsources) | `function` | Declared here | | [`stopSources`](#stopsources) | `function` | Declared here | | [`process`](#process-2) | `function` | Declared here | | [`emit`](#emit) | `function` | Declared here | | [`synchronizeStates`](#synchronizestates) | `function` | Declared here | | [`onStateChange`](#onstatechange) | `function` | Declared here | | [`assertCanModify`](#assertcanmodify) | `function` | Declared here | | [`handleException`](#handleexception) | `function` | Declared here | | [`Ptr`](#ptr-2) | `typedef` | Declared here | | [`StateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#statechange) | `variable` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful-1) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`~Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful-2) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`stateEquals`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateequals) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`stateBetween`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#statebetween) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`state`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#state-4) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`state`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#state-5) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`_state`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#_state) | `variable` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`beforeStateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#beforestatechange) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`onStateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#onstatechange-2) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`setState`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#setstate) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | | [`setState`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#setstate-1) | `function` | Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | ## Inherited from [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful) | Kind | Name | Description | |------|------|-------------| | `variable` | [`StateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#statechange) | Signals when the state changes. | | `function` | [`Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful-1) `inline` | | | `function` | [`~Stateful`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateful-2) `virtual` `inline` | | | `function` | [`stateEquals`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#stateequals) `virtual` `const` `inline` | Returns true if the current state ID equals the given ID. | | `function` | [`stateBetween`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#statebetween) `virtual` `const` `inline` | Returns true if the current state ID is in the inclusive range [lid, rid]. | | `function` | [`state`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#state-4) `virtual` `inline` | Returns a mutable reference to the current state. | | `function` | [`state`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#state-5) `virtual` `const` `inline` | Returns a copy of the current state. | | `variable` | [`_state`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#_state) | | | `function` | [`beforeStateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#beforestatechange) `virtual` `inline` | Override to handle pre state change logic. Return false to prevent state change. | | `function` | [`onStateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#onstatechange-2) `virtual` `inline` | Override to handle post state change logic. | | `function` | [`setState`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#setstate) `virtual` `inline` | Sets the state and sends the state signal if the state change was successful. | | `function` | [`setState`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#setstate-1) `virtual` `inline` | Sets the state and sends the state signal if the state change was successful. | ## Public Attributes | Return | Name | Description | |--------|------|-------------| | [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) | [`emitter`](#emitter-1) | Signals to delegates on outgoing packets. | | [`ThreadSignal`](https://auscaster.com/icey/docs/api-reference/base.md#threadsignal)< void([`PacketStream`](#packetstream) &, const std::exception_ptr &)> | [`Error`](#error-4) | Signals that the [PacketStream](#packetstream) is in [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) state. If stream output is synchronized then the [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) signal will be sent from the synchronization context, otherwise it will be sent from the async processor context. See [synchronizeOutput()](#synchronizeoutput) | | [`ThreadSignal`](https://auscaster.com/icey/docs/api-reference/base.md#threadsignal)< void([`PacketStream`](#packetstream) &)> | [`Close`](#close-2) | Signals that the [PacketStream](#packetstream) is in Close state. This signal is sent immediately via the [close()](#close-3) method, and as such will be sent from the calling thread context. | --- ### emitter ```cpp PacketSignal emitter ``` Type: [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) [Defined in src/base/include/icy/packetstream.h:497](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L497) Signals to delegates on outgoing packets. --- ### Error ```cpp ThreadSignal< void(PacketStream &, const std::exception_ptr &)> Error ``` Type: [`ThreadSignal`](https://auscaster.com/icey/docs/api-reference/base.md#threadsignal)< void([`PacketStream`](#packetstream) &, const std::exception_ptr &)> [Defined in src/base/include/icy/packetstream.h:503](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L503) Signals that the [PacketStream](#packetstream) is in [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) state. If stream output is synchronized then the [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) signal will be sent from the synchronization context, otherwise it will be sent from the async processor context. See [synchronizeOutput()](#synchronizeoutput) --- ### Close ```cpp ThreadSignal< void(PacketStream &)> Close ``` Type: [`ThreadSignal`](https://auscaster.com/icey/docs/api-reference/base.md#threadsignal)< void([`PacketStream`](#packetstream) &)> [Defined in src/base/include/icy/packetstream.h:508](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L508) Signals that the [PacketStream](#packetstream) is in Close state. This signal is sent immediately via the [close()](#close-3) method, and as such will be sent from the calling thread context. ## Public Methods | Return | Name | Description | |--------|------|-------------| | | [`PacketStream`](#packetstream-1) | Construct a named packet stream. | | | [`~PacketStream`](#packetstream-2) `virtual` | Destroy the stream; calls [close()](#close-3) then [reset()](#reset-5) to release all adapters. | | | [`PacketStream`](#packetstream-3) | Deleted constructor. | | [`PacketStream`](#packetstream) & | [`operator=`](#operator-70) | Deleted assignment operator. | | | [`PacketStream`](#packetstream-4) | Deleted constructor. | | [`PacketStream`](#packetstream) & | [`operator=`](#operator-71) | Deleted assignment operator. | | `void` | [`start`](#start-2) `virtual` | Start the stream and synchronized sources. | | `void` | [`stop`](#stop-1) `virtual` | Stop the stream and synchronized sources. | | `void` | [`pause`](#pause-1) `virtual` | Pause the stream. | | `void` | [`resume`](#resume) `virtual` | Resume the stream. | | `void` | [`close`](#close-3) `virtual` | Close the stream and transition the internal state to Closed. | | `void` | [`reset`](#reset-5) `virtual` | Cleanup all managed stream adapters and reset the stream state. | | `bool` | [`active`](#active) `virtual` `const` | Returns true when the stream is in the Active state. | | `bool` | [`stopped`](#stopped) `virtual` `const` | Returns true when the stream is in the Stopping or Stopped state. | | `bool` | [`closed`](#closed) `virtual` `const` | Returns true when the stream is in the Closed or [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) state. | | `bool` | [`lock`](#lock-1) `virtual` | Sets the stream to locked state. In a locked state no new adapters can be added or removed from the stream until the stream is stopped. | | `bool` | [`locked`](#locked) `virtual` `const` | Returns true is the stream is currently locked. | | `void` | [`write`](#write-11) `virtual` | Write a mutable buffer into the stream without copying. The caller must keep the buffer alive until processing crosses a Cloned/Retained boundary or, if the graph is fully synchronous, until [write()](#write-11) returns. | | `void` | [`write`](#write-12) `virtual` | Write a read-only buffer into the stream; data is copied immediately into an owning [RawPacket](https://auscaster.com/icey/docs/api-reference/icy-RawPacket.md#rawpacket-4) before any adapter sees it. | | `void` | [`write`](#write-13) `virtual` | Write a packet directly into the processing chain. | | `void` | [`attachSource`](#attachsource) `virtual` | Attach a bare packet signal as a stream source. The signal is wrapped in an unowned [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) internally. Useful when the source is another [PacketStream::emitter](#emitter-1). | | `void` | [`attachSource`](#attachsource-1) `virtual` | Attach a [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) as a source. Source adapters default to Borrowed retention unless overridden; they must not retain inbound packet storage asynchronously without reporting Cloned or Retained. | | `void` | [`attachSource`](#attachsource-2) `inline` | Attach a shared_ptr-managed source adapter to the stream. The stream shares ownership; the adapter is kept alive at least until teardown. Throws std::runtime_error if `ptr` does not derive from [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter). | | `bool` | [`detachSource`](#detachsource) `virtual` | Detach a source by its packet signal. Disconnects the signal from the stream's process slot and removes the adapter entry. | | `bool` | [`detachSource`](#detachsource-1) `virtual` | Detach a source by its adapter pointer. Disconnects the adapter's emitter from the stream's process slot and removes the entry. | | `void` | [`attach`](#attach) `virtual` | Attach a packet processor to the stream. Processors are executed in ascending order of their `order` value. Pass order = -1 to append at the end of the current processor list. Valid range is -1 to 101; values outside this range throw std::invalid_argument. Borrowed processors must finish with the packet before [process()](#process-2) returns. Queue/processors that defer work must report Cloned or Retained via retention() so upstream code has an explicit ownership boundary. | | `void` | [`attach`](#attach-1) `inline` | Attach a shared_ptr-managed processor to the stream. The stream shares ownership; the processor is kept alive at least until teardown. Throws std::runtime_error if `ptr` does not derive from [PacketProcessor](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor). | | `bool` | [`detach`](#detach-1) `virtual` | Detach a packet processor from the stream. The processor's delegate connections are removed; ownership is released if held. | | `void` | [`synchronizeOutput`](#synchronizeoutput) `virtual` | Synchronize stream output packets with a libuv event loop. Internally attaches a [SyncPacketQueue](https://auscaster.com/icey/docs/api-reference/icy-SyncPacketQueue.md#syncpacketqueue) at order 101 so that all packets emitted by the processor chain are dispatched from the loop thread rather than the source thread. Must be called before [start()](#start-2). | | `void` | [`autoStart`](#autostart) `virtual` | Enable or disable auto-start behaviour (default: false). When enabled, the stream automatically transitions to Active state upon receiving the first packet while in the None or Locked state. Must be called before [start()](#start-2). | | `void` | [`closeOnError`](#closeonerror) `virtual` | Enable or disable close-on-error behaviour (default: true). When enabled, an unhandled processor exception causes the stream to transition from [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) to Closed state automatically. | | `const std::exception_ptr &` | [`error`](#error-5) | Accessors for the unmanaged client data pointer. | | `std::string` | [`name`](#name-2) `const` | Return the name assigned to this stream at construction. | | [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) | [`adapters`](#adapters) `const` | Returns a combined list of all stream sources and processors. | | [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) | [`sources`](#sources) `const` | Returns a list of all stream sources. | | [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) | [`processors`](#processors) `const` | Returns a list of all stream processors. | | `int` | [`numSources`](#numsources) `const` | Return the number of source adapters currently registered. | | `int` | [`numProcessors`](#numprocessors) `const` | Return the number of processor adapters currently registered. | | `int` | [`numAdapters`](#numadapters) `const` | Return the total number of adapters (sources + processors). | | `AdapterT *` | [`getSource`](#getsource) `inline` | Return the nth source of type AdapterT, or nullptr if not found. Sources are searched in their registered order; only adapters that dynamic_cast successfully to AdapterT are counted. | | `AdapterT *` | [`getProcessor`](#getprocessor) `inline` | Return the nth processor of type AdapterT, or nullptr if not found. Processors are searched in their registered order; only adapters that dynamic_cast successfully to AdapterT are counted. | | [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) * | [`getProcessor`](#getprocessor-1) `inline` | Return the processor registered at a specific order value. Unlike the template overload, this searches by order rather than by type and index. | --- ### PacketStream ```cpp PacketStream(const std::string & name = "") ``` [Defined in src/base/include/icy/packetstream.h:315](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L315) Construct a named packet stream. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `name` | `const std::string &` | Optional human-readable name used in log output. | --- ### ~PacketStream `virtual` ```cpp virtual ~PacketStream() ``` [Defined in src/base/include/icy/packetstream.h:318](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L318) Destroy the stream; calls [close()](#close-3) then [reset()](#reset-5) to release all adapters. --- ### PacketStream ```cpp PacketStream(const PacketStream &) = delete ``` [Defined in src/base/include/icy/packetstream.h:320](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L320) Deleted constructor. --- ### operator= ```cpp PacketStream & operator=(const PacketStream &) = delete ``` [Defined in src/base/include/icy/packetstream.h:321](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L321) Deleted assignment operator. --- ### PacketStream ```cpp PacketStream(PacketStream &&) = delete ``` [Defined in src/base/include/icy/packetstream.h:322](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L322) Deleted constructor. --- ### operator= ```cpp PacketStream & operator=(PacketStream &&) = delete ``` [Defined in src/base/include/icy/packetstream.h:323](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L323) Deleted assignment operator. --- ### start `virtual` ```cpp virtual void start() ``` [Defined in src/base/include/icy/packetstream.h:326](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L326) Start the stream and synchronized sources. --- ### stop `virtual` ```cpp virtual void stop() ``` [Defined in src/base/include/icy/packetstream.h:329](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L329) Stop the stream and synchronized sources. --- ### pause `virtual` ```cpp virtual void pause() ``` [Defined in src/base/include/icy/packetstream.h:332](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L332) Pause the stream. --- ### resume `virtual` ```cpp virtual void resume() ``` [Defined in src/base/include/icy/packetstream.h:335](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L335) Resume the stream. --- ### close `virtual` ```cpp virtual void close() ``` [Defined in src/base/include/icy/packetstream.h:338](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L338) Close the stream and transition the internal state to Closed. --- ### reset `virtual` ```cpp virtual void reset() ``` [Defined in src/base/include/icy/packetstream.h:341](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L341) Cleanup all managed stream adapters and reset the stream state. --- ### active `virtual` `const` ```cpp virtual bool active() const ``` [Defined in src/base/include/icy/packetstream.h:344](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L344) Returns true when the stream is in the Active state. --- ### stopped `virtual` `const` ```cpp virtual bool stopped() const ``` [Defined in src/base/include/icy/packetstream.h:347](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L347) Returns true when the stream is in the Stopping or Stopped state. --- ### closed `virtual` `const` ```cpp virtual bool closed() const ``` [Defined in src/base/include/icy/packetstream.h:350](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L350) Returns true when the stream is in the Closed or [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) state. --- ### lock `virtual` ```cpp virtual bool lock() ``` [Defined in src/base/include/icy/packetstream.h:355](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L355) Sets the stream to locked state. In a locked state no new adapters can be added or removed from the stream until the stream is stopped. --- ### locked `virtual` `const` ```cpp virtual bool locked() const ``` [Defined in src/base/include/icy/packetstream.h:358](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L358) Returns true is the stream is currently locked. --- ### write `virtual` ```cpp virtual void write(char * data, size_t len) ``` [Defined in src/base/include/icy/packetstream.h:366](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L366) Write a mutable buffer into the stream without copying. The caller must keep the buffer alive until processing crosses a Cloned/Retained boundary or, if the graph is fully synchronous, until [write()](#write-11) returns. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `data` | `char *` | Pointer to the raw data buffer. | | `len` | `size_t` | Number of bytes to process. | --- ### write `virtual` ```cpp virtual void write(const char * data, size_t len) ``` [Defined in src/base/include/icy/packetstream.h:372](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L372) Write a read-only buffer into the stream; data is copied immediately into an owning [RawPacket](https://auscaster.com/icey/docs/api-reference/icy-RawPacket.md#rawpacket-4) before any adapter sees it. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `data` | `const char *` | Pointer to the raw data buffer. | | `len` | `size_t` | Number of bytes to process. | --- ### write `virtual` ```cpp virtual void write(IPacket && packet) ``` [Defined in src/base/include/icy/packetstream.h:376](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L376) Write a packet directly into the processing chain. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `packet` | [`IPacket`](https://auscaster.com/icey/docs/api-reference/icy-IPacket.md#ipacket) && | Packet to process; moved into the stream. | --- ### attachSource `virtual` ```cpp virtual void attachSource(PacketSignal & source) ``` [Defined in src/base/include/icy/packetstream.h:382](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L382) Attach a bare packet signal as a stream source. The signal is wrapped in an unowned [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) internally. Useful when the source is another [PacketStream::emitter](#emitter-1). #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `source` | [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) & | The packet signal to attach; must outlive the stream. | --- ### attachSource `virtual` ```cpp virtual void attachSource(PacketStreamAdapter * source, bool owned = true, bool syncState = false) ``` [Defined in src/base/include/icy/packetstream.h:392](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L392) Attach a [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) as a source. Source adapters default to Borrowed retention unless overridden; they must not retain inbound packet storage asynchronously without reporting Cloned or Retained. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `source` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) * | The adapter to attach; must not be null. | | `owned` | `bool` | If true the stream takes ownership and deletes the pointer on teardown. | | `syncState` | `bool` | If true and `source` implements [basic::Startable](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable), its [start()](#start-2)/stop() will be called by [startSources()](#startsources)/stopSources(). | --- ### attachSource `inline` ```cpp template inline void attachSource(std::shared_ptr< C > ptr, bool syncState = false) ``` [Defined in src/base/include/icy/packetstream.h:402](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L402) Attach a shared_ptr-managed source adapter to the stream. The stream shares ownership; the adapter is kept alive at least until teardown. Throws std::runtime_error if `ptr` does not derive from [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter). #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `ptr` | `std::shared_ptr< C >` | Shared pointer to the adapter instance. | | `syncState` | `bool` | If true and `ptr` implements [basic::Startable](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable), its [start()](#start-2)/stop() will be called by [startSources()](#startsources)/stopSources(). | --- ### detachSource `virtual` ```cpp virtual bool detachSource(PacketSignal & source) ``` [Defined in src/base/include/icy/packetstream.h:417](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L417) Detach a source by its packet signal. Disconnects the signal from the stream's process slot and removes the adapter entry. #### Returns true if the source was found and removed, false otherwise. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `source` | [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) & | The packet signal previously attached via [attachSource(PacketSignal&)](#attachsource). | --- ### detachSource `virtual` ```cpp virtual bool detachSource(PacketStreamAdapter * source) ``` [Defined in src/base/include/icy/packetstream.h:423](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L423) Detach a source by its adapter pointer. Disconnects the adapter's emitter from the stream's process slot and removes the entry. #### Returns true if the source was found and removed, false otherwise. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `source` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) * | Pointer to the adapter previously attached. | --- ### attach `virtual` ```cpp virtual void attach(PacketProcessor * proc, int order = 0, bool owned = true) ``` [Defined in src/base/include/icy/packetstream.h:435](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L435) Attach a packet processor to the stream. Processors are executed in ascending order of their `order` value. Pass order = -1 to append at the end of the current processor list. Valid range is -1 to 101; values outside this range throw std::invalid_argument. Borrowed processors must finish with the packet before [process()](#process-2) returns. Queue/processors that defer work must report Cloned or Retained via retention() so upstream code has an explicit ownership boundary. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `proc` | [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) * | The processor to attach; must not be null. | | `order` | `int` | Position in the processing chain (lower runs first). | | `owned` | `bool` | If true the stream takes ownership and deletes the pointer on teardown. | --- ### attach `inline` ```cpp template inline void attach(std::shared_ptr< C > ptr, int order = 0, bool syncState = false) ``` [Defined in src/base/include/icy/packetstream.h:445](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L445) Attach a shared_ptr-managed processor to the stream. The stream shares ownership; the processor is kept alive at least until teardown. Throws std::runtime_error if `ptr` does not derive from [PacketProcessor](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor). #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `ptr` | `std::shared_ptr< C >` | Shared pointer to the processor instance. | | `order` | `int` | Position in the processing chain (lower runs first). | | `syncState` | `bool` | Reserved for future use; currently unused. | --- ### detach `virtual` ```cpp virtual bool detach(PacketProcessor * proc) ``` [Defined in src/base/include/icy/packetstream.h:461](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L461) Detach a packet processor from the stream. The processor's delegate connections are removed; ownership is released if held. #### Returns true if the processor was found and removed, false otherwise. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `proc` | [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) * | Pointer to the processor to remove. | --- ### synchronizeOutput `virtual` ```cpp virtual void synchronizeOutput(uv::Loop * loop) ``` [Defined in src/base/include/icy/packetstream.h:468](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L468) Synchronize stream output packets with a libuv event loop. Internally attaches a [SyncPacketQueue](https://auscaster.com/icey/docs/api-reference/icy-SyncPacketQueue.md#syncpacketqueue) at order 101 so that all packets emitted by the processor chain are dispatched from the loop thread rather than the source thread. Must be called before [start()](#start-2). #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `loop` | [`uv::Loop`](https://auscaster.com/icey/docs/api-reference/uv.md#loop-1) * | The event loop to synchronize output onto; must not be null. | --- ### autoStart `virtual` ```cpp virtual void autoStart(bool flag) ``` [Defined in src/base/include/icy/packetstream.h:475](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L475) Enable or disable auto-start behaviour (default: false). When enabled, the stream automatically transitions to Active state upon receiving the first packet while in the None or Locked state. Must be called before [start()](#start-2). #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `flag` | `bool` | true to enable auto-start, false to disable. | --- ### closeOnError `virtual` ```cpp virtual void closeOnError(bool flag) ``` [Defined in src/base/include/icy/packetstream.h:481](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L481) Enable or disable close-on-error behaviour (default: true). When enabled, an unhandled processor exception causes the stream to transition from [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) to Closed state automatically. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `flag` | `bool` | true to close the stream on error, false to remain in [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) state. | --- ### error ```cpp const std::exception_ptr & error() ``` [Defined in src/base/include/icy/packetstream.h:490](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L490) Accessors for the unmanaged client data pointer. Return the last captured exception, if the stream is in [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) state. The pointer is null when no error has occurred. #### Returns A reference to the stored exception_ptr; empty if no error. --- ### name `const` ```cpp std::string name() const ``` [Defined in src/base/include/icy/packetstream.h:494](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L494) Return the name assigned to this stream at construction. #### Returns The stream name; empty string if none was provided. --- ### adapters `const` ```cpp PacketAdapterVec adapters() const ``` [Defined in src/base/include/icy/packetstream.h:511](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L511) Returns a combined list of all stream sources and processors. --- ### sources `const` ```cpp PacketAdapterVec sources() const ``` [Defined in src/base/include/icy/packetstream.h:514](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L514) Returns a list of all stream sources. --- ### processors `const` ```cpp PacketAdapterVec processors() const ``` [Defined in src/base/include/icy/packetstream.h:517](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L517) Returns a list of all stream processors. --- ### numSources `const` ```cpp int numSources() const ``` [Defined in src/base/include/icy/packetstream.h:521](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L521) Return the number of source adapters currently registered. #### Returns Source count; thread-safe. --- ### numProcessors `const` ```cpp int numProcessors() const ``` [Defined in src/base/include/icy/packetstream.h:525](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L525) Return the number of processor adapters currently registered. #### Returns Processor count; thread-safe. --- ### numAdapters `const` ```cpp int numAdapters() const ``` [Defined in src/base/include/icy/packetstream.h:529](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L529) Return the total number of adapters (sources + processors). #### Returns Combined adapter count; thread-safe. --- ### getSource `inline` ```cpp template inline AdapterT * getSource(int index = 0) ``` [Defined in src/base/include/icy/packetstream.h:538](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L538) Return the nth source of type AdapterT, or nullptr if not found. Sources are searched in their registered order; only adapters that dynamic_cast successfully to AdapterT are counted. #### Returns Pointer to the matching adapter, or nullptr. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `index` | `int` | Zero-based index among matching sources (default 0). | --- ### getProcessor `inline` ```cpp template inline AdapterT * getProcessor(int index = 0) ``` [Defined in src/base/include/icy/packetstream.h:561](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L561) Return the nth processor of type AdapterT, or nullptr if not found. Processors are searched in their registered order; only adapters that dynamic_cast successfully to AdapterT are counted. #### Returns Pointer to the matching processor, or nullptr. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `index` | `int` | Zero-based index among matching processors (default 0). | --- ### getProcessor `inline` ```cpp inline PacketProcessor * getProcessor(int order = 0) ``` [Defined in src/base/include/icy/packetstream.h:581](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L581) Return the processor registered at a specific order value. Unlike the template overload, this searches by order rather than by type and index. #### Returns Pointer to the matching processor, or nullptr if none registered at that order. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `order` | `int` | The order value to match (default 0). | ## Protected Attributes | Return | Name | Description | |--------|------|-------------| | `std::mutex` | [`_mutex`](#_mutex-3) | | | `std::mutex` | [`_procMutex`](#_procmutex) | | | `std::atomic< std::thread::id >` | [`_procMutexOwner`](#_procmutexowner) | [Thread](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1) currently holding `_procMutex` inside [`process()`](#process-2). Lets [`emit()`](#emit) detect that handling an exception inline ([close()](#close-3) -> [stop()](#stop-1) re-locks `_procMutex`) would self-deadlock, and rethrow to [`process()`](#process-2) instead. | | `std::string` | [`_name`](#_name-1) | | | [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) | [`_sources`](#_sources) | | | [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) | [`_processors`](#_processors) | | | std::deque< [`PacketStreamState`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamState.md#packetstreamstate) > | [`_states`](#_states) | | | `std::exception_ptr` | [`_error`](#_error) | | | `bool` | [`_autoStart`](#_autostart) | | | `bool` | [`_closeOnError`](#_closeonerror) | | | `bool` | [`_wired`](#_wired) | | --- ### _mutex ```cpp std::mutex _mutex ``` [Defined in src/base/include/icy/packetstream.h:635](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L635) --- ### _procMutex ```cpp std::mutex _procMutex ``` [Defined in src/base/include/icy/packetstream.h:636](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L636) --- ### _procMutexOwner ```cpp std::atomic< std::thread::id > _procMutexOwner {} ``` [Defined in src/base/include/icy/packetstream.h:640](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L640) [Thread](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1) currently holding `_procMutex` inside [`process()`](#process-2). Lets [`emit()`](#emit) detect that handling an exception inline ([close()](#close-3) -> [stop()](#stop-1) re-locks `_procMutex`) would self-deadlock, and rethrow to [`process()`](#process-2) instead. --- ### _name ```cpp std::string _name ``` [Defined in src/base/include/icy/packetstream.h:641](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L641) --- ### _sources ```cpp PacketAdapterVec _sources ``` Type: [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) [Defined in src/base/include/icy/packetstream.h:642](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L642) --- ### _processors ```cpp PacketAdapterVec _processors ``` Type: [`PacketAdapterVec`](https://auscaster.com/icey/docs/api-reference/base.md#packetadaptervec) [Defined in src/base/include/icy/packetstream.h:643](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L643) --- ### _states ```cpp std::deque< PacketStreamState > _states ``` Type: std::deque< [`PacketStreamState`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamState.md#packetstreamstate) > [Defined in src/base/include/icy/packetstream.h:644](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L644) --- ### _error ```cpp std::exception_ptr _error ``` [Defined in src/base/include/icy/packetstream.h:645](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L645) --- ### _autoStart ```cpp bool _autoStart ``` [Defined in src/base/include/icy/packetstream.h:646](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L646) --- ### _closeOnError ```cpp bool _closeOnError ``` [Defined in src/base/include/icy/packetstream.h:647](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L647) --- ### _wired ```cpp bool _wired ``` [Defined in src/base/include/icy/packetstream.h:648](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L648) ## Protected Methods | Return | Name | Description | |--------|------|-------------| | `void` | [`setup`](#setup) | Attach the source and processor delegate chain. | | `void` | [`teardown`](#teardown) | Detach the source and processor delegate chain. | | `void` | [`attachSource`](#attachsource-3) | | | `void` | [`attach`](#attach-2) | | | `void` | [`startSources`](#startsources) | Start synchronized sources. | | `void` | [`stopSources`](#stopsources) | Stop synchronized sources. | | `void` | [`process`](#process-2) `virtual` | [Process](https://auscaster.com/icey/docs/api-reference/icy-Process.md#process-3) incoming packets. | | `void` | [`emit`](#emit) | Emit the final packet to listeners. | | `void` | [`synchronizeStates`](#synchronizestates) | Synchronize queued states with adapters. | | `void` | [`onStateChange`](#onstatechange) `virtual` `override` | Override the [Stateful::onStateChange](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#onstatechange-2) method. | | `void` | [`assertCanModify`](#assertcanmodify) | Returns true if the given state ID is queued. | | `void` | [`handleException`](#handleexception) | Handle an internal exception. | --- ### setup ```cpp void setup() ``` [Defined in src/base/include/icy/packetstream.h:596](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L596) Attach the source and processor delegate chain. --- ### teardown ```cpp void teardown() ``` [Defined in src/base/include/icy/packetstream.h:599](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L599) Detach the source and processor delegate chain. --- ### attachSource ```cpp void attachSource(PacketAdapterReference::Ptr ref) ``` [Defined in src/base/include/icy/packetstream.h:601](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L601) --- ### attach ```cpp void attach(PacketAdapterReference::Ptr ref) ``` [Defined in src/base/include/icy/packetstream.h:602](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L602) --- ### startSources ```cpp void startSources() ``` [Defined in src/base/include/icy/packetstream.h:605](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L605) Start synchronized sources. --- ### stopSources ```cpp void stopSources() ``` [Defined in src/base/include/icy/packetstream.h:608](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L608) Stop synchronized sources. --- ### process `virtual` ```cpp virtual void process(IPacket & packet) ``` [Defined in src/base/include/icy/packetstream.h:611](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L611) [Process](https://auscaster.com/icey/docs/api-reference/icy-Process.md#process-3) incoming packets. --- ### emit ```cpp void emit(IPacket & packet) ``` [Defined in src/base/include/icy/packetstream.h:617](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L617) Emit the final packet to listeners. Synchronized signals such as Close and [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) are sent from this method. See [synchronizeOutput()](#synchronizeoutput) --- ### synchronizeStates ```cpp void synchronizeStates() ``` [Defined in src/base/include/icy/packetstream.h:620](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L620) Synchronize queued states with adapters. --- ### onStateChange `virtual` `override` ```cpp virtual void onStateChange(PacketStreamState & state, const PacketStreamState & oldState) override ``` [Defined in src/base/include/icy/packetstream.h:623](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L623) Override the [Stateful::onStateChange](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#onstatechange-2) method. #### Reimplements - [`Stateful::onStateChange`](https://auscaster.com/icey/docs/api-reference/icy-Stateful.md#onstatechange-2) --- ### assertCanModify ```cpp void assertCanModify() ``` [Defined in src/base/include/icy/packetstream.h:630](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L630) Returns true if the given state ID is queued. Asserts that the stream can be modified, ie is not in the Locked, Stopping or Active states. --- ### handleException ```cpp void handleException(std::exception & exc) ``` [Defined in src/base/include/icy/packetstream.h:633](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L633) Handle an internal exception. ## Public Types | Name | Description | |------|-------------| | [`Ptr`](#ptr-2) | | --- ### Ptr ```cpp using Ptr = std::shared_ptr< PacketStream > ``` Type: std::shared_ptr< [`PacketStream`](#packetstream) > [Defined in src/base/include/icy/packetstream.h:311](https://github.com/auscaster/icey/blob/main/src/base/include/icy/packetstream.h#L311)