nanocoat/include/sjme/circleBuffer.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Circular buffer, also known as a round robin.
  12  *
  13  * @since 2024/08/25
  14  */
  15
  16 #ifndef SQUIRRELJME_CIRCLEBUFFER_H
  17 #define SQUIRRELJME_CIRCLEBUFFER_H
  18
  19 #include "sjme/error.h"
  20 #include "sjme/stdTypes.h"
  21 #include "sjme/alloc.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_CIRCLEBUFFER_H
  28 extern "C"
  29 {
  30         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  31 #endif /* #ifdef __cplusplus */
  32
  33 /*--------------------------------------------------------------------------*/
  34
  35 /**
  36  * Represents the mode of how the buffer acts.
  37  *
  38  * @since 2024/08/25
  39  */
  40 typedef enum sjme_circleBuffer_mode
  41 {
  42         /** The buffer acts as a queue. */
  43         SJME_CIRCLE_BUFFER_QUEUE,
  44
  45         /** The buffer acts as a circular window. */
  46         SJME_CIRCLE_BUFFER_WINDOW,
  47
  48         /** The number of overflow modes. */
  49         SJME_CIRCLE_BUFFER_NUM_MODES,
  50 } sjme_circleBuffer_mode;
  51
  52 /**
  53  * Used to refer to the front or the back of a circular buffer.
  54  *
  55  * @since 2024/08/25
  56  */
  57 typedef enum sjme_circleBuffer_seekEnd
  58 {
  59         /** The front/head of the buffer. */
  60         SJME_CIRCLE_BUFFER_HEAD,
  61
  62         /** The back/tail of the buffer. */
  63         SJME_CIRCLE_BUFFER_TAIL,
  64
  65         /** The number of seek ends. */
  66         SJME_CIRCLE_BUFFER_NUM_SEEK_END,
  67
  68         /** The front/head of the buffer. */
  69         SJME_CIRCLE_BUFFER_FIRST = SJME_CIRCLE_BUFFER_HEAD,
  70
  71         /** The back/tail of the buffer. */
  72         SJME_CIRCLE_BUFFER_LAST = SJME_CIRCLE_BUFFER_TAIL,
  73
  74         /** The front/head of the buffer. */
  75         SJME_CIRCLE_BUFFER_FRONT = SJME_CIRCLE_BUFFER_HEAD,
  76
  77         /** The back/tail of the buffer. */
  78         SJME_CIRCLE_BUFFER_BACK = SJME_CIRCLE_BUFFER_TAIL,
  79 } sjme_circleBuffer_seekEnd;
  80
  81 /**
  82  * Represents a circle buffer and its data.
  83  *
  84  * @since 2024/08/25
  85  */
  86 typedef struct sjme_circleBuffer
  87 {
  88         /** The buffer mode. */
  89         sjme_circleBuffer_mode mode;
  90
  91         /** The size of the buffer. */
  92         sjme_jint size;
  93
  94         /** The amount of data that is in the buffer. */
  95         sjme_jint ready;
  96
  97         /** The current read head. */
  98         sjme_jint readHead;
  99
 100         /** The current write head. */
 101         sjme_jint writeHead;
 102
 103         /** The buffer storage. */
 104         sjme_jubyte* buffer;
 105 } sjme_circleBuffer;
 106
 107 /**
 108  * Returns the number of bytes that are free within the buffer.
 109  *
 110  * @param buffer The buffer to get the empty space of.
 111  * @param outAvailable The number of bytes not used in the buffer that
 112  * are available.
 113  * @return Any resultant error, if any.
 114  * @since 2024/08/25
 115  */
 116 sjme_errorCode sjme_circleBuffer_available(
 117         sjme_attrInNotNull sjme_circleBuffer* buffer,
 118         sjme_attrOutNotNull sjme_jint* outAvailable);
 119
 120 /**
 121  * Destroys the buffer and frees any associated memory.
 122  *
 123  * @param buffer The buffer to free.
 124  * @return Any resultant error, if any.
 125  * @since 2024/08/25
 126  */
 127 sjme_errorCode sjme_circleBuffer_destroy(
 128         sjme_attrInNotNull sjme_circleBuffer* buffer);
 129
 130 /**
 131  * Gets data from the buffer, without removing it, from the specified end
 132  * and position.
 133  *
 134  * @param buffer The buffer to read from.
 135  * @param outData The destination buffer.
 136  * @param length The number of bytes to read.
 137  * @param seekType Seek from the head or tail?
 138  * @param seekPos The seek position, relative to @c seekType .
 139  * @return Any resultant error, if any.
 140  * @since 2024/08/25
 141  */
 142 sjme_errorCode sjme_circleBuffer_get(
 143         sjme_attrInNotNull sjme_circleBuffer* buffer,
 144         sjme_attrOutNotNullBuf(length) sjme_pointer outData,
 145         sjme_attrInPositiveNonZero sjme_jint length,
 146         sjme_attrInValue sjme_circleBuffer_seekEnd seekType,
 147         sjme_attrInPositiveNonZero sjme_jint seekPos);
 148
 149 /**
 150  * Allocates a new circular buffer.
 151  *
 152  * @param allocPool The pool to allocate within.
 153  * @param outBuffer The resultant newly created buffer.
 154  * @param inMode The mode that the buffer should be using.
 155  * @param length The maximum length of the buffer to allocate.
 156  * @return On any resultant error, if any.
 157  * @since 2024/08/25
 158  */
 159 sjme_errorCode sjme_circleBuffer_new(
 160         sjme_attrInNotNull sjme_alloc_pool allocPool,
 161         sjme_attrOutNotNull sjme_circleBuffer** outBuffer,
 162         sjme_attrInValue sjme_circleBuffer_mode inMode,
 163         sjme_attrInPositiveNonZero sjme_jint length);
 164
 165 /**
 166  * Removes data from the buffer at the given end.
 167  *
 168  * @param buffer The buffer to remove from.
 169  * @param outData The resultant data that was in the buffer.
 170  * @param length The number of bytes to remove.
 171  * @param seekType Remove from the head or the tail?
 172  * @return On any resultant error, if any.
 173  * @since 2024/08/25
 174  */
 175 sjme_errorCode sjme_circleBuffer_pop(
 176         sjme_attrInNotNull sjme_circleBuffer* buffer,
 177         sjme_attrOutNotNullBuf(length) sjme_pointer outData,
 178         sjme_attrInPositiveNonZero sjme_jint length,
 179         sjme_attrInValue sjme_circleBuffer_seekEnd seekType);
 180
 181 /**
 182  * Pushes data to the buffer at the given end.
 183  *
 184  * @param buffer The buffer to add to.
 185  * @param inData The data to be added.
 186  * @param length The number of bytes to add.
 187  * @param seekType Add at the head or the tail?
 188  * @return On any resultant error, if any.
 189  * @since 2024/08/25
 190  */
 191 sjme_errorCode sjme_circleBuffer_push(
 192         sjme_attrInNotNull sjme_circleBuffer* buffer,
 193         sjme_attrInNotNullBuf(length) sjme_cpointer inData,
 194         sjme_attrInPositiveNonZero sjme_jint length,
 195         sjme_attrInValue sjme_circleBuffer_seekEnd seekType);
 196
 197 /**
 198  * Returns the current amount of data that is stored in the buffer.
 199  *
 200  * @param buffer The buffer to get the current amount of data in.
 201  * @param outStored The number of bytes stored in the buffer.
 202  * @return Any resultant error, if any.
 203  * @since 2024/08/25
 204  */
 205 sjme_errorCode sjme_circleBuffer_stored(
 206         sjme_attrInNotNull sjme_circleBuffer* buffer,
 207         sjme_attrOutNotNull sjme_jint* outStored);
 208
 209 /*--------------------------------------------------------------------------*/
 210
 211 /* Anti-C++. */
 212 #ifdef __cplusplus
 213         #ifdef SJME_CXX_SQUIRRELJME_CIRCLEBUFFER_H
 214 }
 215                 #undef SJME_CXX_SQUIRRELJME_CIRCLEBUFFER_H
 216                 #undef SJME_CXX_IS_EXTERNED
 217         #endif /* #ifdef SJME_CXX_SQUIRRELJME_CIRCLEBUFFER_H */
 218 #endif /* #ifdef __cplusplus */
 219
 220 #endif /* SQUIRRELJME_CIRCLEBUFFER_H */