xStreamBatchingBufferCreate

Collaboration diagram for xStreamBatchingBufferCreate:

stream_buffer.h

StreamBufferHandle_t xStreamBatchingBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );

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 for FreeRTOSConfig.h for xStreamBatchingBufferCreate() to be available.

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

• The task reading from a non-empty stream buffer returns immediately regardless of the amount of data in the buffer.
• The task reading from a non-empty steam 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	Callback invoked when number of bytes at least equal to trigger level is sent to the stream batching buffer. If the parameter is NULL, it will use the default implementation provided by sbSEND_COMPLETED macro. To enable the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h.
pxReceiveCompletedCallback	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 sbRECEIVE_COMPLETED macro. To enable the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h.

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. A non-NULL value being returned 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:

void vAFunction( void )
{
StreamBufferHandle_t xStreamBatchingBuffer;
const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
 
 // Create a stream batching buffer that can hold 100 bytes.  The memory used
 // to hold both the stream batching buffer structure and the data in the stream
 // batching buffer is allocated dynamically.
 xStreamBatchingBuffer = xStreamBatchingBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
 
 if( xStreamBatchingBuffer == NULL )
 {
     // There was not enough heap memory space available to create the
     // stream batching buffer.
 }
 else
 {
     // The stream batching buffer was created successfully and can now be used.
 }
}