Stream objects

Stream objects are used to read, write, and manage a stream of binary data.

Stream creation and deletion

The function osCreateStream creates a stream object. The stream can be created before system start, from an interrupt handler or by a task. During stream creation, an optional stream name may be specified. It makes tasks able to open it by osOpenStream function. During stream creation and opening, its handle is returned. The handle is assigned by the system and it is used to discern the system objects. All operations performed on the stream except to specify its handle. The non-used stream should be closed with the osCloseHandle. Stream will be deleted when it will be closed by all tasks that opened it. More information you can find in the system objects management section.

When streams are not used, the OS_USE_STREAM constant may be set to 0, to reduce the output code.

Using a stream object

When the stream object instance is created, a data buffer with specified size is allocated. The buffer is used to store the data between the write operation that is performed by one task and the read operation performed by the other tasks.

A variable number of data bytes can be read or written from this buffer and it is performed by two system functions i.e. osRead and osWrite. The data are put on the stream byte per byte and read from it in order they were put.

Access to stream synchronization is realized in three ways. It may be protected by mutex, auto-reset event, or by interrupt disabling for data copy time. The last way can be realized only when small portions of data are transferred to or from a stream. The way of synchronization is chosen during stream creation by using OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT or OS_IPC_PROTECT_INT_CTRL mode flag. Synchronization mode by mutex or auto-reset event is available only when corresponding constant OS_STREAM_PROTECT_MUTEX and OS_STREAM_PROTECT_EVENT are set to 1.

When read operation is performed on the stream with an empty buffer, or write operation when the buffer is full, the operation will be finished with an error. If only part of data is transferred to or from buffer, the operation will be performed only for the available number of bytes and just after it will be finished with success.

The task may also be waiting for a completion of read or write operation and it is resumed when all data will be successfully transferred, or specified timeout interval elapses. It is realized by specifying the appropriate mode flags OS_IPC_WAIT_IF_EMPTY and OS_IPC_WAIT_IF_FULL during the stream creation. These operations are available only when the corresponding constants OS_STREAM_ALLOW_WAIT_IF_EMPTY and OS_STREAM_ALLOW_WAIT_IF_FULL are set to 1.

When the wait for operation completion is enabled, the data can be sending directly from one task to another, without storing data in the buffer. To enable this feature, it should be set OS_IPC_DIRECT_READ_WRITE mode flag and it is only available when OS_STREAM_ALLOW_DIRECT_RW is set to 1.

SpaceShadow documentation