PBuf is a Prioritised buffer intended for use in an embedded environment, with processors or controllers as small as 8-bit.
PBuf can be used to enable the rapid re-prioritisation of self-contained payloads of data, possibly compressed and encrypted. It makes sense to manipulate such a payload in units of payload, and being able to prioritise or re-order the delivery of them against time can release the business logic from being required to maintain a lot of state regarding what has gone, what has maybe gone, and how urgent is this payload with respect to what is already out there. By employing prioritisation in this way, the priorities may be worked out ahead of time, and the configuration stored as constant data for rapid use, freeing the user of much of the decision-making in real-time.
It is configurable at compile time by defining three definitions (found in priority_buffer.h). The definitions can also be passed to the compiler via the command line.
BUFFER_SIZEis the number of buffer elements (3 to 256).ELEMENT_SIZEis the size of each element (8, 16, 32, or 64 bits).PRIORITY_SIZEis the number of priorities used by the buffer (2 to 8).
The compilation will fail if other values are attempted.
By default these are set to 4, 8 and 3 respectively.
There is also a headless mode configurable by defining EXTERNAL_DATA_BUFFER. In this mode no internal buffer storage is
allocated and code associated with the internal buffer is not built. This allows the user to maintain an external buffer
structure and have PBuf figure out the correct insertion and retrieval points based on priorities. See the PBUF_insertIndex()
and PBUF_retrieveIndex() API commands.
A test suite is available in test/ and can be run by typing make in the root directory.
The testing framework used is Unity Test System. The test runners are written in C to avoid other dependencies. Unity Test System is MIT licensed.
A cli program is available in cli/.
This buffer exerciser is configured for an eight element buffer with four priorities, but may be adjusted with configuration (see makefile).
It enables for the inserting, retrieving, viewing and resetting of data in a prioritised buffer.
To build cli run make build_cli
To run cli run make run_cli
Documentation is present in the docs directory and is available at the link below.
The documentation is available here.
The source documentation is cross-referenced using Doxygen. and can be built using the command make doc.
There is a Graphviz dependency to build the graphs.
There are currently no locks or checks for concurrency, so it is the responsibility of the user to ensure reads and writes do not occur simultaneously. This is by design, since the user has control over their interrupts etc.
PBuf has a permissive MIT license (see ./LICENSE)