diff options
Diffstat (limited to 'kernel/ringbuffer.h')
| -rw-r--r-- | kernel/ringbuffer.h | 62 |
1 files changed, 43 insertions, 19 deletions
diff --git a/kernel/ringbuffer.h b/kernel/ringbuffer.h index f68f766..9610150 100644 --- a/kernel/ringbuffer.h +++ b/kernel/ringbuffer.h @@ -8,16 +8,37 @@ * * Requires * -------- + * * Requires kballoc/kbfree - block allocation * - * Thread - * ------ - * This is __not__ threadsafe. It is your job to lock accesses to - * reads/writes. + * Thread Safety + * ------------- + * + * **NOTE** : If you have more than one producer and one consumer + * you will have to do some locking! + * + * ringbuffer_init() and ringbuffer_free() can be logically called only + * once anyway (for each ringbuffer). + * + * The structure is believed to be thread-safe as long as you have + * ONLY _ONE_ single producer AND _ONE_ single consumer PER ringbuffer. + * + * With one Consumer and one Producer: + * + * The Consumer can use: + * - ringbuffer_has() - will not give false positives. + * - ringbuffer_empty() - will not give false negatives. + * - ringbuffer_get() - acceseses only the head-pointer. + * + * The Producer can use: + * - ringbuffer_not_full() - will not give false positives + * - ringbuffer_full() - will not give false negatives. + * - ringbuffer_put() - accesses only the tail-pointer. * * Todo * ---- - * provide soemthing to read large blocks faster? + * provide soemthing to read large blocks faster. + * */ #ifndef RINGBUFFER_H @@ -27,12 +48,12 @@ #include <stdbool.h> /** Ringbuffer sturcutre */ -typedef struct ringbuffer_struct +typedef struct ringbuffer_struct { - uint32_t size; - uint32_t front; - uint32_t back; - uint8_t *data; + uint32_t size; // size in bytes + uint32_t head; // current head idx + uint32_t tail; // current tail idx + uint8_t *data; // the data itself }ringbuffer; /** Create a new fifo/ringbuffer of given size (in blocks) */ @@ -41,19 +62,22 @@ ringbuffer ringbuffer_init(uint32_t blocks); /** Deallocate buffer */ void ringbuffer_free(ringbuffer *f); -/** Put one _char_ into buffer. Returns true on success (i.e. buffer not full) */ -bool ringbuffer_put(ringbuffer*,uint8_t); +/** Put one _byte_ into the buffer. */ +bool ringbuffer_put(ringbuffer*,uint8_t); -/** Get a single _char_ from the buffer, - * Return value __0__ might indicate that the buffer is empty. - * check with _ringbuffer_has()_ to be sure. - */ +/** Get a single _byte_ from the buffer. */ uint8_t ringbuffer_get(ringbuffer*); -/** Check if buffer is not empty */ -bool ringbuffer_has(ringbuffer*); +/** Check if the buffer is not empty */ +bool ringbuffer_has(ringbuffer*); -/** Check if buffer is full */ +/** Check if the buffer is empty */ +bool ringbuffer_empty(ringbuffer*); + +/** Check if the buffer is full */ bool ringbuffer_full(ringbuffer* f); +/** Check if the buffer is not full */ +bool ringbuffer_not_full(ringbuffer* f); + #endif |