circular buffer in Linux kernel

/*
 * See Documentation/circular-buffers.txt for more information.
 */

#ifndef _LINUX_CIRC_BUF_H
#define _LINUX_CIRC_BUF_H 1

struct circ_buf {
 char *buf;
 int head;
 int tail;
};

/* Return count in buffer.  */
#define CIRC_CNT(head,tail,size) (((head) - (tail)) & ((size)-1))

/* Return space available, 0..size-1.  We always leave one free char
   as a completely full buffer has head == tail, which is the same as
   empty.  */
#define CIRC_SPACE(head,tail,size) CIRC_CNT((tail),((head)+1),(size))

/* Return count up to the end of the buffer.  Carefully avoid
   accessing head and tail more than once, so they can change
   underneath us without returning inconsistent results.  */
#define CIRC_CNT_TO_END(head,tail,size) \
 ({int end = (size) - (tail); \
   int n = ((head) + end) & ((size)-1); \
   n < end ? n : end;})

/* Return space available up to the end of the buffer.  */
#define CIRC_SPACE_TO_END(head,tail,size) \
 ({int end = (size) - 1 - (head); \
   int n = (end + (tail)) & ((size)-1); \
   n <= end ? n : end+1;})

#endif /* _LINUX_CIRC_BUF_H  */

All these macros only apply to power-of-2 buffers.

 

Each of these macros will nominally return a value between 0 and buffer_size-1,
however:

 [1] CIRC_SPACE*() are intended to be used in the producer.  To the producer
     they will return a lower bound as the producer controls the head index,
     but the consumer may still be depleting the buffer on another CPU and
     moving the tail index.

     To the consumer it will show an upper bound as the producer may be busy
     depleting the space.

 [2] CIRC_CNT*() are intended to be used in the consumer.  To the consumer they
     will return a lower bound as the consumer controls the tail index, but the
     producer may still be filling the buffer on another CPU and moving the
     head index.

     To the producer it will show an upper bound as the consumer may be busy
     emptying the buffer.

 [3] To a third party, the order in which the writes to the indices by the
     producer and consumer become visible cannot be guaranteed as they are
     independent and may be made on different CPUs - so the result in such a
     situation will merely be a guess, and may even be negative.

 =========================================== USING MEMORY BARRIERS WITH CIRCULAR BUFFERS ===========================================