1 /*---------------------------------------------------------------------------* 2 * CircularBuffer.h * 3 * * 4 * Copyright 2007, 2008 Nuance Communciations, Inc. * 5 * * 6 * Licensed under the Apache License, Version 2.0 (the 'License'); * 7 * you may not use this file except in compliance with the License. * 8 * * 9 * You may obtain a copy of the License at * 10 * http://www.apache.org/licenses/LICENSE-2.0 * 11 * * 12 * Unless required by applicable law or agreed to in writing, software * 13 * distributed under the License is distributed on an 'AS IS' BASIS, * 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * 15 * See the License for the specific language governing permissions and * 16 * limitations under the License. * 17 * * 18 *---------------------------------------------------------------------------*/ 19 20 #ifndef CIRCULARBUFFER_H 21 #define CIRCULARBUFFER_H 22 23 24 25 /* 26 * This is implemented as a set of macros rather than functions with proper 27 * checking. The reasons for doing so is that this is a non-public API that is 28 * used in the audio delivery component and we want it to be as fast as 29 * possible. 30 */ 31 32 #include "ESR_SharedPrefix.h" 33 #include "ptypes.h" 34 35 /** 36 * @addtogroup CircularBufferModule CircularBuffer API functions 37 * Generic Circular Buffer implementation. 38 * 39 * @{ 40 */ 41 42 /** 43 * A circular buffer. 44 * 45 * @see list of functions used to operate on @ref CircularBufferModule "CircularBuffer" objects 46 */ 47 typedef struct CircularBuffer_t 48 { 49 /** 50 * Total buffer capacity. 51 */ 52 size_t capacity; 53 54 /** 55 * Amount of data in buffer. 56 */ 57 size_t size; 58 59 /** 60 * Write index. 61 */ 62 size_t writeIdx; 63 64 /** 65 * Read index. 66 */ 67 size_t readIdx; 68 69 } 70 CircularBuffer; 71 72 /** 73 * Creates a circular buffer of the specified capacity. 74 * 75 * @param capacity the capacity in number of bytes of the data buffer. 76 * @param mtag MALLOC allocation tag 77 * @param buffer The circular buffer to initialize. 78 */ 79 ESR_SHARED_API ESR_ReturnCode CircularBufferCreate(size_t capacity, const LCHAR* mtag, CircularBuffer** buffer); 80 81 /** 82 * Returns the capacity of the buffer. 83 */ 84 #define CircularBufferGetCapacity(buffer) ((buffer)->capacity + 0) 85 86 /** 87 * Returns the current size (number of bytes) in the buffer. 88 */ 89 #define CircularBufferGetSize(buffer) ((buffer)->size + 0) 90 91 /** 92 * Returns whether buffer is empty or not. 93 */ 94 #define CircularBufferIsEmpty(buffer) ((buffer)->size == 0) 95 96 /** 97 * Returns whether buffer is full or not. 98 **/ 99 #define CircularBufferIsFull(buffer) ((buffer)->size == (buffer)->capacity) 100 101 /** 102 * Resets the buffer to the empty state. 103 */ 104 #define CircularBufferReset(buffer) ((buffer)->size = \ 105 (buffer)->readIdx = \ 106 (buffer)->writeIdx = 0) 107 108 /** 109 * Determines the residual capacity of the circular buffer. 110 */ 111 #define CircularBufferGetAvailable(buffer) ((buffer)->capacity - (buffer)->size) 112 113 /** 114 * Reads requested number of bytes from the circular buffer. 115 * 116 * @param buffer The circular buffer to read from. 117 * @param data Pointer to where to store read bytes. 118 * @param bufSize The number of bytes to read from the circular buffer. 119 * 120 * @return the number of bytes that were read. A negative value indicates an 121 * error, while a value less than bufSize indicates that end-of-buffer is 122 * reached. 123 */ 124 ESR_SHARED_API int CircularBufferRead(CircularBuffer* buffer, void* data, size_t bufSize); 125 126 /** 127 * Skips requested number of bytes from the circular buffer. 128 * 129 * @param buffer The circular buffer to skip from. 130 * @param bufSize The number of bytes to skip from the circular buffer. 131 * 132 * @return the number of bytes that were skipped. A negative value indicates an 133 * error, while a value less than bufSize indicates that end-of-buffer is 134 * reached. 135 **/ 136 ESR_SHARED_API int CircularBufferSkip(CircularBuffer* buffer, size_t bufSize); 137 138 /** 139 * Writes requested number of bytes from the circular buffer. 140 * 141 * @param buffer The circular buffer to write to 142 * @param data Pointer to data to write. 143 * @param bufSize The number of bytes to write into the circular buffer. 144 * 145 * @return the number of bytes that were written. A negative value indicates 146 * an error, while a value less than bufSize indicates that buffer capacity is 147 * reached. 148 */ 149 ESR_SHARED_API int CircularBufferWrite(CircularBuffer* buffer, const void* data, size_t bufSize); 150 151 /** 152 * Removes the requested number of bytes from the end of the circular buffer. 153 * 154 * @param buffer The circular buffer to write to 155 * @param amoun tThe number of bytes to remove from end of circular buffer. 156 * 157 * @return the number of bytes that were unwritten. A negative value indicates 158 * an error. 159 */ 160 ESR_SHARED_API int CircularBufferUnwrite(CircularBuffer* buffer, size_t amount); 161 162 /** 163 * @} 164 */ 165 166 167 #endif 168