Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Updated Jun 2025

xStreamBatchingBufferCreate() / xStreamBatchingBufferCreateWithCallback()

[RTOS Stream Buffer API]

stream_buffer.h

1StreamBufferHandle_t xStreamBatchingBufferCreate( size_t xBufferSizeBytes,
2 size_t xTriggerLevelBytes );
3
4StreamBufferHandle_t xStreamBatchingBufferCreateWithCallback(
5 size_t xBufferSizeBytes,
6 size_t xTriggerLevelBytes
7 StreamBufferCallbackFunction_t pxSendCompletedCallback,
8 StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

Creates a new stream batching buffer using dynamically allocated memory. See xStreamBatchingBufferCreateStatic() for a version that uses statically allocated memory (memory that is allocated at compile time).

configSUPPORT_DYNAMIC_ALLOCATION
must be set to 1 or left undefined in FreeRTOSConfig.h for
xStreamBatchingBufferCreate()
to be available.
configUSE_STREAM_BUFFERS
must be set to 1 in FreeRTOSConfig.h for
xStreamBatchingBufferCreate()
to be available. Additionally,
configUSE_SB_COMPLETED_CALLBACK
must be set to 1 in FreeRTOSConfig.h for
xStreamBatchingBufferCreateWithCallback()
to be available.

Enable stream buffer functionality by including the FreeRTOS/source/stream_buffer.c source file in the build.

The difference between a stream buffer and a stream batching buffer is when a task performs a read on a non-empty buffer:

  • A task that reads from a non-empty stream buffer returns immediately regardless of the amount of data in the buffer.

  • A task that reads from a non-empty stream batching buffer blocks until the amount of data in the buffer exceeds the trigger level or the block time expires.

Parameters:

  • xBufferSizeBytes

    The total number of bytes the stream batching buffer will be able to hold at any one time.

  • xTriggerLevelBytes

    The number of bytes that must be in the stream batching buffer to unblock a task calling

    xStreamBufferReceive
    before the block time expires.

  • pxSendCompletedCallback

    The callback invoked when a number of bytes at least equal to the trigger level are sent to the stream batching buffer. If the parameter is NULL, it will use the default implementation provided by the

    sbSEND_COMPLETED
    macro. To enable the callback,
    configUSE_SB_COMPLETED_CALLBACK
    must be set to 1 in FreeRTOSConfig.h. The send completed callback function must have the prototype defined by
    StreamBufferCallbackFunction_t
    , which is:

    1void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
    2 BaseType_t xIsInsideISR,
    3 BaseType_t * const pxHigherPriorityTaskWoken );
  • pxReceiveCompletedCallback

    The callback invoked when more than zero bytes are read from a stream batching buffer. If the parameter is NULL, it will use the default implementation provided by the

    sbRECEIVE_COMPLETED
    macro. To enable the callback,
    configUSE_SB_COMPLETED_CALLBACK
    must be set to 1 in FreeRTOSConfig.h. The receive completed callback function must have the prototype defined by
    StreamBufferCallbackFunction_t
    , which is:

    1void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
    2 BaseType_t xIsInsideISR,
    3 BaseType_t * const pxHigherPriorityTaskWoken );

Returns:

  • If NULL is returned, then the stream batching buffer cannot be created because there is insufficient heap memory available for FreeRTOS to allocate the stream batching buffer data structures and storage area.

  • The return of a non-NULL value indicates that the stream batching buffer has been created successfully - the returned value should be stored as the handle to the created stream batching buffer.

Example use:

1void vAFunction( void )
2{
3StreamBufferHandle_t xStreamBatchingBuffer;
4const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
5
6 // Create a stream batching buffer that can hold 100 bytes. The memory used
7 // to hold both the stream batching buffer structure and the data in the stream
8 // batching buffer is allocated dynamically.
9 xStreamBatchingBuffer = xStreamBatchingBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
10
11 if( xStreamBatchingBuffer == NULL )
12 {
13 // There was not enough heap memory space available to create the
14 // stream batching buffer.
15 }
16 else
17 {
18 // The stream batching buffer was created successfully and can now be used.
19 }
20}