fifo.h (8487B)
1 /* 2 * This file is part of FFmpeg. 3 * 4 * FFmpeg is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * FFmpeg is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with FFmpeg; if not, write to the Free Software 16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 17 */ 18 19 /** 20 * @file 21 * @ingroup lavu_fifo 22 * A generic FIFO API 23 */ 24 25 #ifndef AVUTIL_FIFO_H 26 #define AVUTIL_FIFO_H 27 28 #include <stddef.h> 29 30 /** 31 * @defgroup lavu_fifo AVFifo 32 * @ingroup lavu_data 33 * 34 * @{ 35 * A generic FIFO API 36 */ 37 38 typedef struct AVFifo AVFifo; 39 40 /** 41 * Callback for writing or reading from a FIFO, passed to (and invoked from) the 42 * av_fifo_*_cb() functions. It may be invoked multiple times from a single 43 * av_fifo_*_cb() call and may process less data than the maximum size indicated 44 * by nb_elems. 45 * 46 * @param opaque the opaque pointer provided to the av_fifo_*_cb() function 47 * @param buf the buffer for reading or writing the data, depending on which 48 * av_fifo_*_cb function is called 49 * @param nb_elems On entry contains the maximum number of elements that can be 50 * read from / written into buf. On success, the callback should 51 * update it to contain the number of elements actually written. 52 * 53 * @return 0 on success, a negative error code on failure (will be returned from 54 * the invoking av_fifo_*_cb() function) 55 */ 56 typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems); 57 58 /** 59 * Automatically resize the FIFO on writes, so that the data fits. This 60 * automatic resizing happens up to a limit that can be modified with 61 * av_fifo_auto_grow_limit(). 62 */ 63 #define AV_FIFO_FLAG_AUTO_GROW (1 << 0) 64 65 /** 66 * Allocate and initialize an AVFifo with a given element size. 67 * 68 * @param elems initial number of elements that can be stored in the FIFO 69 * @param elem_size Size in bytes of a single element. Further operations on 70 * the returned FIFO will implicitly use this element size. 71 * @param flags a combination of AV_FIFO_FLAG_* 72 * 73 * @return newly-allocated AVFifo on success, a negative error code on failure 74 */ 75 AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size, 76 unsigned int flags); 77 78 /** 79 * @return Element size for FIFO operations. This element size is set at 80 * FIFO allocation and remains constant during its lifetime 81 */ 82 size_t av_fifo_elem_size(const AVFifo *f); 83 84 /** 85 * Set the maximum size (in elements) to which the FIFO can be resized 86 * automatically. Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used. 87 */ 88 void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems); 89 90 /** 91 * @return number of elements available for reading from the given FIFO. 92 */ 93 size_t av_fifo_can_read(const AVFifo *f); 94 95 /** 96 * @return Number of elements that can be written into the given FIFO without 97 * growing it. 98 * 99 * In other words, this number of elements or less is guaranteed to fit 100 * into the FIFO. More data may be written when the 101 * AV_FIFO_FLAG_AUTO_GROW flag was specified at FIFO creation, but this 102 * may involve memory allocation, which can fail. 103 */ 104 size_t av_fifo_can_write(const AVFifo *f); 105 106 /** 107 * Enlarge an AVFifo. 108 * 109 * On success, the FIFO will be large enough to hold exactly 110 * inc + av_fifo_can_read() + av_fifo_can_write() 111 * elements. In case of failure, the old FIFO is kept unchanged. 112 * 113 * @param f AVFifo to resize 114 * @param inc number of elements to allocate for, in addition to the current 115 * allocated size 116 * @return a non-negative number on success, a negative error code on failure 117 */ 118 int av_fifo_grow2(AVFifo *f, size_t inc); 119 120 /** 121 * Write data into a FIFO. 122 * 123 * In case nb_elems > av_fifo_can_write(f) and the AV_FIFO_FLAG_AUTO_GROW flag 124 * was not specified at FIFO creation, nothing is written and an error 125 * is returned. 126 * 127 * Calling function is guaranteed to succeed if nb_elems <= av_fifo_can_write(f). 128 * 129 * @param f the FIFO buffer 130 * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be 131 * read from buf on success. 132 * @param nb_elems number of elements to write into FIFO 133 * 134 * @return a non-negative number on success, a negative error code on failure 135 */ 136 int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems); 137 138 /** 139 * Write data from a user-provided callback into a FIFO. 140 * 141 * @param f the FIFO buffer 142 * @param read_cb Callback supplying the data to the FIFO. May be called 143 * multiple times. 144 * @param opaque opaque user data to be provided to read_cb 145 * @param nb_elems Should point to the maximum number of elements that can be 146 * written. Will be updated to contain the number of elements 147 * actually written. 148 * 149 * @return non-negative number on success, a negative error code on failure 150 */ 151 int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb, 152 void *opaque, size_t *nb_elems); 153 154 /** 155 * Read data from a FIFO. 156 * 157 * In case nb_elems > av_fifo_can_read(f), nothing is read and an error 158 * is returned. 159 * 160 * @param f the FIFO buffer 161 * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes 162 * will be written into buf on success. 163 * @param nb_elems number of elements to read from FIFO 164 * 165 * @return a non-negative number on success, a negative error code on failure 166 */ 167 int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems); 168 169 /** 170 * Feed data from a FIFO into a user-provided callback. 171 * 172 * @param f the FIFO buffer 173 * @param write_cb Callback the data will be supplied to. May be called 174 * multiple times. 175 * @param opaque opaque user data to be provided to write_cb 176 * @param nb_elems Should point to the maximum number of elements that can be 177 * read. Will be updated to contain the total number of elements 178 * actually sent to the callback. 179 * 180 * @return non-negative number on success, a negative error code on failure 181 */ 182 int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb, 183 void *opaque, size_t *nb_elems); 184 185 /** 186 * Read data from a FIFO without modifying FIFO state. 187 * 188 * Returns an error if an attempt is made to peek to nonexistent elements 189 * (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)). 190 * 191 * @param f the FIFO buffer 192 * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes 193 * will be written into buf. 194 * @param nb_elems number of elements to read from FIFO 195 * @param offset number of initial elements to skip. 196 * 197 * @return a non-negative number on success, a negative error code on failure 198 */ 199 int av_fifo_peek(const AVFifo *f, void *buf, size_t nb_elems, size_t offset); 200 201 /** 202 * Feed data from a FIFO into a user-provided callback. 203 * 204 * @param f the FIFO buffer 205 * @param write_cb Callback the data will be supplied to. May be called 206 * multiple times. 207 * @param opaque opaque user data to be provided to write_cb 208 * @param nb_elems Should point to the maximum number of elements that can be 209 * read. Will be updated to contain the total number of elements 210 * actually sent to the callback. 211 * @param offset number of initial elements to skip; offset + *nb_elems must not 212 * be larger than av_fifo_can_read(f). 213 * 214 * @return a non-negative number on success, a negative error code on failure 215 */ 216 int av_fifo_peek_to_cb(const AVFifo *f, AVFifoCB write_cb, void *opaque, 217 size_t *nb_elems, size_t offset); 218 219 /** 220 * Discard the specified amount of data from an AVFifo. 221 * @param size number of elements to discard, MUST NOT be larger than 222 * av_fifo_can_read(f) 223 */ 224 void av_fifo_drain2(AVFifo *f, size_t size); 225 226 /* 227 * Empty the AVFifo. 228 * @param f AVFifo to reset 229 */ 230 void av_fifo_reset2(AVFifo *f); 231 232 /** 233 * Free an AVFifo and reset pointer to NULL. 234 * @param f Pointer to an AVFifo to free. *f == NULL is allowed. 235 */ 236 void av_fifo_freep2(AVFifo **f); 237 238 /** 239 * @} 240 */ 241 242 #endif /* AVUTIL_FIFO_H */