NAME ringbuf -- implement the ring buffer SYNOPSIS ringbuf [-v] _commands_ DESCRIPTION Creates a ring buffer of characters of default size 16 characters and applies the enqueue/dequeue commands from string _commands_. The _commands_ string is understood as follows: For each character c in _commands_, in order, either: * if the character is a "-", dequeue a character from the ring buffer and print it; print "empty" if there is no character to dequeue; * if the character is a "+", call each of the ioctl's and print the return values; * else enqueue the character c on the ring buffer and print c; print "full" if c cannot be enqueued because the ring buffer is full. The following options are available: -v verbose output OUTPUT The output for enqueue must be the line "enq: _X_", where _X_ is the enqueued character or the word "full". The output for dequeue must be "deq: _X_", where _X_ is the dequeued character or the word "empty". The output for the ioctl query must be "ioc: _X_" where _X_ is the white-space separated result of each of the three ioctl calls, RB_Q_SIZE, RB_IS_EMPTY, RB_IS_FULL and RB_Q_COUNT. If the input is unacceptable, the program will exit with usage message: usage: ringbuf [-v] _commands_ HISTORY Reworked in csc421.171 to unify application and kernel variants. Introduced in csc421.161 to prepare for the in-kernel ring buffer Introduced in csc421.151 as a C warm-up. BUGS ------------------------------------------------------------ NAME rb_enqueue, rb_dequeue, rb_ioctl - ringbuffer subroutines LIBRARY Implemented in ringbuf-sub.c. SYNOPSIS #include "ringbuf.h" #define RB_Q_SIZE 0 #define RB_IS_EMPTY 1 #define RB_IS_FULL 2 #define RB_Q_COUNT 3 int rb_ioctl(int op) ; int rb_enqueue(int ele) ; int rb_dequeue(void) ; DESCRIPTION rb_enqueue takes a character argument ele and places it in the ringbuffer returning ele if successful; if the queue is full or other error return -1. rb_dequeue returns the dequeued element from the queue; if the queue is empty or other error return -1. rb_ioctl performs the ioctl p and returns the result: RB_Q_SIZE: returns the size of the queue (always 16). RB_IS_EMPTY: return 1 if the queue is empty, 0 otherwise RB_IS_FULL: return 1 if the queue is full, 0 otherwise RB_Q_COUNT: return the number of items in the queue Note that ele is passed as an integer, but it is undefined if it is not in the range of an unsigned character, 0 through 255. Note that return character is an integer, but should either be the integer -1 or in the range of an unsigned character, 0 through 255.
You have been provided with the structure "struct RingBuf". This fields in this structure will be used to implement a ring buffer according the algorithm given here. C does not, in general, assure that variables are initialized. However, static variables can have initializers, and are otherwise zero'ed, as they are allocated from zero'ed pages.
head
is the index in ringbuf
to where the next character
should be enqueued. If the ring buffer is named rb, then this is
rb.ringbuf[rb.head].If the buffer is not full, place the character to enqueue at index
head
then increment
head
, taking it mod RINGBUF_SIZE
to wrap around to the beginning of the buffer.
If the buffer is full, return -1, and do not enqueue the character, do not increment
head
.
tail
is the index in ringbuf
from where the next character
should be dequeued. If the ring buffer pointer is named rb, then this is
rb.ringbuf[rb.tail].If the buffer is not empty, return the character at index
tail
, then increment
tail
, taking it mod RINGBUF_SIZE
to wrap around to the beginning of the buffer.
If the buffer is empty, return -1, and do not increment
tail
.
head != tail
, the ring buffer is neither empty nor full. head
gives
the "empty space" ready to take a character; tail
gives the "full space" ready
to provide a character.
head == tail
, the ring buffer might be empty or might be full. You
need to keep track of which of the two situations is the case by maintaining is_full
properly.
is_full
is false (zero). In this case head == tail
because there is nothing
in the ring buffer.
is_full
true (to one) when an enqueue operation causes head
to equal tail
.
is_full
false (to zero) whenever a character is dequeued — the buffer
cannot be full if something has just been removed.
author: burton rosenberg
created: 08 sep 2015
update: 27 aug 2020