Stream objects are utilized to read, write, and manage continuous streams of binary data.

The osCreateStream function is used to create a stream object. A stream may be created prior to system initialization, from within an interrupt handler, or by a running task. During stream creation, an optional name may be assigned to the object, allowing tasks to access it via the osOpenStream function. Both creation and opening functions return a handle assigned by the system to identify the object. All subsequent stream operations require this handle as a reference. When a stream is no longer required, it should be closed using osCloseHandle. The stream object is deleted only after all tasks holding an open handle have closed it. For further details, refer to the System Objects Management section.

If stream objects are not utilized in the application, the OS_USE_STREAM constant can be set to 0 to reduce the total code size.

Upon the creation of a stream object instance, a data buffer of a specified size is allocated. This buffer facilitates data exchange between a writing task and one or more reading tasks.

Variable-length data segments can be read from or written to this buffer using the osRead and osWrite system functions. Data is processed byte-by-byte in the order it was written, maintaining a First-In, First-Out (FIFO) sequence.

Synchronization for stream access is implemented in three ways: via a mutex, an auto-reset event, or by disabling interrupts during the data copy operation. The latter is recommended only for small data transfers. The synchronization method is selected at creation time using the OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT, or OS_IPC_PROTECT_INT_CTRL mode flags. Mutex and event-based synchronization are only available if the OS_STREAM_PROTECT_MUTEX or OS_STREAM_PROTECT_EVENT constants are set to 1, respectively.

If a read operation is attempted on an empty buffer, or a write operation on a full buffer, the function will return an error. If only a portion of the requested data can be transferred, the operation will process the available bytes and then return successfully.

A task may also block while waiting for a read or write operation to complete. In this case, the task is resumed once the transfer is finished or a specified timeout expires. This behavior is enabled by using the OS_IPC_WAIT_IF_EMPTY and OS_IPC_WAIT_IF_FULL mode flags during stream creation. These features require the OS_STREAM_ALLOW_WAIT_IF_EMPTY and OS_STREAM_ALLOW_WAIT_IF_FULL constants to be set to 1.

When blocking operations are enabled, data can be transferred directly between tasks without intermediate buffering. To enable this optimization, use the OS_IPC_DIRECT_READ_WRITE mode flag; this feature is available only when OS_STREAM_ALLOW_DIRECT_RW is set to 1.