\page UtilsTypesLibrary Utils::Types Library

Utils/Types

This directory contains a library of helper types.

Circular Buffer

This type uses a circular buffer to implement a bounded FIFO stream, i.e., a logical store that can grow to a maximum size and can shrink. The logical store is byte addressable with addresses 0 through n - 1, where n is the current store size. It grows by increasing the top address from n - 1 to n + m - 1 and copying m bytes of data into the logical memory so allocated. It shrinks by deleting the lowest m addresses and renumbering the logical addresses of the remaining bytes starting at zero.

The implementation uses a fixed-size physical store. The logical store is represented as a base or head index into the physical store and an allocated size. Initially both are zero. When data is added to the circular buffer, the allocated size grows. When data is removed from the circular buffer, the allocated size shrinks, and the head pointer advances.

The allocated store size never exceeds the physical store size. However, when the head index is greater than zero, the sum of the head index and the allocated size may exceed the physical store size. In this case, the logical store wraps around to the beginning of the physical store. Further, deleting data while in this state may cause the head index to wrap around.

CircularBuffer does not provide concurrency control. If multiple threads use the buffer, the uses must be guarded by other concurrency control, e.g., a queue or lock.

The CircularBuffer type provides the following operations.

Constructor

CircularBuffer(U8* const buffer, const NATIVE_UINT_TYPE size)

Construct a circular buffer with the given physical store, specified as a starting pointer and a size in bytes.

Adding Data

Fw::SerializeStatus serialize(const U8* const buffer, const NATIVE_UINT_TYPE size);

If the current logical store size plus size exceeds the maximum logical store size, then return an error. Otherwise increase the logical store size by size bytes and copy size bytes starting at buffer into the new logical memory.

The operation is called serialize following F Prime practice. No data is actually serialized (the data is copied byte for byte).

Reading Data

Fw::SerializeStatus peek(char& value, NATIVE_UINT_TYPE offset = 0) const;

If offset is not a valid address of the logical store, then return an error. Otherwise read a char value at address offset of the logical store and store the result into value.

Fw::SerializeStatus peek(U8& value, NATIVE_UINT_TYPE offset = 0) const;

Same as previous, but read a U8 value.

Fw::SerializeStatus peek(U32& value, NATIVE_UINT_TYPE offset = 0) const;

If offset through offset + 3 are not valid addresses in the logical store, then return an error. Otherwise read four bytes of the logical store starting at offset, interpret them as an unsigned 32-bit integer in big endian order, and store the result into value.

Fw::SerializeStatus peek(U8* buffer, NATIVE_UINT_TYPE size, NATIVE_UINT_TYPE offset = 0) const;

If offset through offset + size - 1 are not all valid addresses in the logical store, then return an error. Otherwise copy size bytes starting at offset into the memory starting at buffer.

Deleting Data

Fw::SerializeStatus rotate(NATIVE_UINT_TYPE amount);

If the logical store size s is less than amount, then return an error. Otherwise delete amount bytes from the bottom of the logical store: reassign the bytes at addresses amount through s - 1 to addresses zero through s - amount - 1, and set the logical store size to s - amount.

Querying Buffer State

NATIVE_UINT_TYPE get_allocated_size() const;

Return the number of allocated bytes, i.e., the current logical store size. This is the maximum number of bytes that may be read from the logical store without adding data.

NATIVE_UINT_TYPE get_free_size() const;

Return the number of free bytes, i.e., the maximum logical store size minus the current logical store size. This is the number of bytes that may be added to the logical store without deleting data.

NATIVE_UINT_TYPE get_capacity() const;

Return the maximum logical store size (equal to the physical store size). This is the total number of bytes that may be added to an empty circular buffer.