libavutil/fifo.h

   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  * a very simple circular buffer FIFO implementation
  22  */
  23
  24 #ifndef AVUTIL_FIFO_H
  25 #define AVUTIL_FIFO_H
  26
  27 #include <stddef.h>
  28 #include <stdint.h>
  29
  30 #include "attributes.h"
  31 #include "version.h"
  32
  33 typedef struct AVFifo AVFifo;
  34
  35 /**
  36  * Callback for writing or reading from a FIFO, passed to (and invoked from) the
  37  * av_fifo_*_cb() functions. It may be invoked multiple times from a single
  38  * av_fifo_*_cb() call and may process less data than the maximum size indicated
  39  * by nb_elems.
  40  *
  41  * @param opaque the opaque pointer provided to the av_fifo_*_cb() function
  42  * @param buf the buffer for reading or writing the data, depending on which
  43  *            av_fifo_*_cb function is called
  44  * @param nb_elems On entry contains the maximum number of elements that can be
  45  *                 read from / written into buf. On success, the callback should
  46  *                 update it to contain the number of elements actually written.
  47  *
  48  * @return 0 on success, a negative error code on failure (will be returned from
  49  *         the invoking av_fifo_*_cb() function)
  50  */
  51 typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems);
  52
  53 /**
  54  * Automatically resize the FIFO on writes, so that the data fits. This
  55  * automatic resizing happens up to a limit that can be modified with
  56  * av_fifo_auto_grow_limit().
  57  */
  58 #define AV_FIFO_FLAG_AUTO_GROW      (1 << 0)
  59
  60 /**
  61  * Allocate and initialize an AVFifo with a given element size.
  62  *
  63  * @param elems     initial number of elements that can be stored in the FIFO
  64  * @param elem_size Size in bytes of a single element. Further operations on
  65  *                  the returned FIFO will implicitly use this element size.
  66  * @param flags a combination of AV_FIFO_FLAG_*
  67  *
  68  * @return newly-allocated AVFifo on success, a negative error code on failure
  69  */
  70 AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size,
  71                        unsigned int flags);
  72
  73 /**
  74  * @return Element size for FIFO operations. This element size is set at
  75  *         FIFO allocation and remains constant during its lifetime
  76  */
  77 size_t av_fifo_elem_size(const AVFifo *f);
  78
  79 /**
  80  * Set the maximum size (in elements) to which the FIFO can be resized
  81  * automatically. Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used.
  82  */
  83 void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems);
  84
  85 /**
  86  * @return number of elements available for reading from the given FIFO.
  87  */
  88 size_t av_fifo_can_read(const AVFifo *f);
  89
  90 /**
  91  * @return number of elements that can be written into the given FIFO.
  92  */
  93 size_t av_fifo_can_write(const AVFifo *f);
  94
  95 /**
  96  * Enlarge an AVFifo.
  97  *
  98  * On success, the FIFO will be large enough to hold exactly
  99  * inc + av_fifo_can_read() + av_fifo_can_write()
 100  * elements. In case of failure, the old FIFO is kept unchanged.
 101  *
 102  * @param f AVFifo to resize
 103  * @param inc number of elements to allocate for, in addition to the current
 104  *            allocated size
 105  * @return a non-negative number on success, a negative error code on failure
 106  */
 107 int av_fifo_grow2(AVFifo *f, size_t inc);
 108
 109 /**
 110  * Write data into a FIFO.
 111  *
 112  * In case nb_elems > av_fifo_can_write(f), nothing is written and an error
 113  * is returned.
 114  *
 115  * @param f the FIFO buffer
 116  * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be
 117  *            read from buf on success.
 118  * @param nb_elems number of elements to write into FIFO
 119  *
 120  * @return a non-negative number on success, a negative error code on failure
 121  */
 122 int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems);
 123
 124 /**
 125  * Write data from a user-provided callback into a FIFO.
 126  *
 127  * @param f the FIFO buffer
 128  * @param read_cb Callback supplying the data to the FIFO. May be called
 129  *                multiple times.
 130  * @param opaque opaque user data to be provided to read_cb
 131  * @param nb_elems Should point to the maximum number of elements that can be
 132  *                 written. Will be updated to contain the number of elements
 133  *                 actually written.
 134  *
 135  * @return non-negative number on success, a negative error code on failure
 136  */
 137 int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb,
 138                           void *opaque, size_t *nb_elems);
 139
 140 /**
 141  * Read data from a FIFO.
 142  *
 143  * In case nb_elems > av_fifo_can_read(f), nothing is read and an error
 144  * is returned.
 145  *
 146  * @param f the FIFO buffer
 147  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
 148  *            will be written into buf on success.
 149  * @param nb_elems number of elements to read from FIFO
 150  *
 151  * @return a non-negative number on success, a negative error code on failure
 152  */
 153 int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems);
 154
 155 /**
 156  * Feed data from a FIFO into a user-provided callback.
 157  *
 158  * @param f the FIFO buffer
 159  * @param write_cb Callback the data will be supplied to. May be called
 160  *                 multiple times.
 161  * @param opaque opaque user data to be provided to write_cb
 162  * @param nb_elems Should point to the maximum number of elements that can be
 163  *                 read. Will be updated to contain the total number of elements
 164  *                 actually sent to the callback.
 165  *
 166  * @return non-negative number on success, a negative error code on failure
 167  */
 168 int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb,
 169                        void *opaque, size_t *nb_elems);
 170
 171 /**
 172  * Read data from a FIFO without modifying FIFO state.
 173  *
 174  * Returns an error if an attempt is made to peek to nonexistent elements
 175  * (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)).
 176  *
 177  * @param f the FIFO buffer
 178  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
 179  *            will be written into buf.
 180  * @param nb_elems number of elements to read from FIFO
 181  * @param offset number of initial elements to skip.
 182  *
 183  * @return a non-negative number on success, a negative error code on failure
 184  */
 185 int av_fifo_peek(AVFifo *f, void *buf, size_t nb_elems, size_t offset);
 186
 187 /**
 188  * Feed data from a FIFO into a user-provided callback.
 189  *
 190  * @param f the FIFO buffer
 191  * @param write_cb Callback the data will be supplied to. May be called
 192  *                 multiple times.
 193  * @param opaque opaque user data to be provided to write_cb
 194  * @param nb_elems Should point to the maximum number of elements that can be
 195  *                 read. Will be updated to contain the total number of elements
 196  *                 actually sent to the callback.
 197  * @param offset number of initial elements to skip; offset + *nb_elems must not
 198  *               be larger than av_fifo_can_read(f).
 199  *
 200  * @return a non-negative number on success, a negative error code on failure
 201  */
 202 int av_fifo_peek_to_cb(AVFifo *f, AVFifoCB write_cb, void *opaque,
 203                        size_t *nb_elems, size_t offset);
 204
 205 /**
 206  * Discard the specified amount of data from an AVFifo.
 207  * @param size number of elements to discard, MUST NOT be larger than
 208  *             av_fifo_can_read(f)
 209  */
 210 void av_fifo_drain2(AVFifo *f, size_t size);
 211
 212 /*
 213  * Empty the AVFifo.
 214  * @param f AVFifo to reset
 215  */
 216 void av_fifo_reset2(AVFifo *f);
 217
 218 /**
 219  * Free an AVFifo and reset pointer to NULL.
 220  * @param f Pointer to an AVFifo to free. *f == NULL is allowed.
 221  */
 222 void av_fifo_freep2(AVFifo **f);
 223
 224
 225 #if FF_API_FIFO_OLD_API
 226 typedef struct AVFifoBuffer {
 227     uint8_t *buffer;
 228     uint8_t *rptr, *wptr, *end;
 229     uint32_t rndx, wndx;
 230 } AVFifoBuffer;
 231
 232 /**
 233  * Initialize an AVFifoBuffer.
 234  * @param size of FIFO
 235  * @return AVFifoBuffer or NULL in case of memory allocation failure
 236  * @deprecated use av_fifo_alloc2()
 237  */
 238 attribute_deprecated
 239 AVFifoBuffer *av_fifo_alloc(unsigned int size);
 240
 241 /**
 242  * Initialize an AVFifoBuffer.
 243  * @param nmemb number of elements
 244  * @param size  size of the single element
 245  * @return AVFifoBuffer or NULL in case of memory allocation failure
 246  * @deprecated use av_fifo_alloc2()
 247  */
 248 attribute_deprecated
 249 AVFifoBuffer *av_fifo_alloc_array(size_t nmemb, size_t size);
 250
 251 /**
 252  * Free an AVFifoBuffer.
 253  * @param f AVFifoBuffer to free
 254  * @deprecated use the AVFifo API with av_fifo_freep2()
 255  */
 256 attribute_deprecated
 257 void av_fifo_free(AVFifoBuffer *f);
 258
 259 /**
 260  * Free an AVFifoBuffer and reset pointer to NULL.
 261  * @param f AVFifoBuffer to free
 262  * @deprecated use the AVFifo API with av_fifo_freep2()
 263  */
 264 attribute_deprecated
 265 void av_fifo_freep(AVFifoBuffer **f);
 266
 267 /**
 268  * Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
 269  * @param f AVFifoBuffer to reset
 270  * @deprecated use av_fifo_reset2() with the new AVFifo-API
 271  */
 272 attribute_deprecated
 273 void av_fifo_reset(AVFifoBuffer *f);
 274
 275 /**
 276  * Return the amount of data in bytes in the AVFifoBuffer, that is the
 277  * amount of data you can read from it.
 278  * @param f AVFifoBuffer to read from
 279  * @return size
 280  * @deprecated use av_fifo_can_read() with the new AVFifo-API
 281  */
 282 attribute_deprecated
 283 int av_fifo_size(const AVFifoBuffer *f);
 284
 285 /**
 286  * Return the amount of space in bytes in the AVFifoBuffer, that is the
 287  * amount of data you can write into it.
 288  * @param f AVFifoBuffer to write into
 289  * @return size
 290  * @deprecated use av_fifo_can_write() with the new AVFifo-API
 291  */
 292 attribute_deprecated
 293 int av_fifo_space(const AVFifoBuffer *f);
 294
 295 /**
 296  * Feed data at specific position from an AVFifoBuffer to a user-supplied callback.
 297  * Similar as av_fifo_gereric_read but without discarding data.
 298  * @param f AVFifoBuffer to read from
 299  * @param offset offset from current read position
 300  * @param buf_size number of bytes to read
 301  * @param func generic read function
 302  * @param dest data destination
 303  *
 304  * @return a non-negative number on success, a negative error code on failure
 305  *
 306  * @deprecated use the new AVFifo-API with av_fifo_peek() when func == NULL,
 307  *             av_fifo_peek_to_cb() otherwise
 308  */
 309 attribute_deprecated
 310 int av_fifo_generic_peek_at(AVFifoBuffer *f, void *dest, int offset, int buf_size, void (*func)(void*, void*, int));
 311
 312 /**
 313  * Feed data from an AVFifoBuffer to a user-supplied callback.
 314  * Similar as av_fifo_gereric_read but without discarding data.
 315  * @param f AVFifoBuffer to read from
 316  * @param buf_size number of bytes to read
 317  * @param func generic read function
 318  * @param dest data destination
 319  *
 320  * @return a non-negative number on success, a negative error code on failure
 321  *
 322  * @deprecated use the new AVFifo-API with av_fifo_peek() when func == NULL,
 323  *             av_fifo_peek_to_cb() otherwise
 324  */
 325 attribute_deprecated
 326 int av_fifo_generic_peek(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
 327
 328 /**
 329  * Feed data from an AVFifoBuffer to a user-supplied callback.
 330  * @param f AVFifoBuffer to read from
 331  * @param buf_size number of bytes to read
 332  * @param func generic read function
 333  * @param dest data destination
 334  *
 335  * @return a non-negative number on success, a negative error code on failure
 336  *
 337  * @deprecated use the new AVFifo-API with av_fifo_read() when func == NULL,
 338  *             av_fifo_read_to_cb() otherwise
 339  */
 340 attribute_deprecated
 341 int av_fifo_generic_read(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
 342
 343 /**
 344  * Feed data from a user-supplied callback to an AVFifoBuffer.
 345  * @param f AVFifoBuffer to write to
 346  * @param src data source; non-const since it may be used as a
 347  * modifiable context by the function defined in func
 348  * @param size number of bytes to write
 349  * @param func generic write function; the first parameter is src,
 350  * the second is dest_buf, the third is dest_buf_size.
 351  * func must return the number of bytes written to dest_buf, or <= 0 to
 352  * indicate no more data available to write.
 353  * If func is NULL, src is interpreted as a simple byte array for source data.
 354  * @return the number of bytes written to the FIFO or a negative error code on failure
 355  *
 356  * @deprecated use the new AVFifo-API with av_fifo_write() when func == NULL,
 357  *             av_fifo_write_from_cb() otherwise
 358  */
 359 attribute_deprecated
 360 int av_fifo_generic_write(AVFifoBuffer *f, void *src, int size, int (*func)(void*, void*, int));
 361
 362 /**
 363  * Resize an AVFifoBuffer.
 364  * In case of reallocation failure, the old FIFO is kept unchanged.
 365  *
 366  * @param f AVFifoBuffer to resize
 367  * @param size new AVFifoBuffer size in bytes
 368  * @return <0 for failure, >=0 otherwise
 369  *
 370  * @deprecated use the new AVFifo-API with av_fifo_grow2() to increase FIFO size,
 371  *             decreasing FIFO size is not supported
 372  */
 373 attribute_deprecated
 374 int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size);
 375
 376 /**
 377  * Enlarge an AVFifoBuffer.
 378  * In case of reallocation failure, the old FIFO is kept unchanged.
 379  * The new fifo size may be larger than the requested size.
 380  *
 381  * @param f AVFifoBuffer to resize
 382  * @param additional_space the amount of space in bytes to allocate in addition to av_fifo_size()
 383  * @return <0 for failure, >=0 otherwise
 384  *
 385  * @deprecated use the new AVFifo-API with av_fifo_grow2(); note that unlike
 386  * this function it adds to the allocated size, rather than to the used size
 387  */
 388 attribute_deprecated
 389 int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space);
 390
 391 /**
 392  * Read and discard the specified amount of data from an AVFifoBuffer.
 393  * @param f AVFifoBuffer to read from
 394  * @param size amount of data to read in bytes
 395  *
 396  * @deprecated use the new AVFifo-API with av_fifo_drain2()
 397  */
 398 attribute_deprecated
 399 void av_fifo_drain(AVFifoBuffer *f, int size);
 400
 401 #if FF_API_FIFO_PEEK2
 402 /**
 403  * Return a pointer to the data stored in a FIFO buffer at a certain offset.
 404  * The FIFO buffer is not modified.
 405  *
 406  * @param f    AVFifoBuffer to peek at, f must be non-NULL
 407  * @param offs an offset in bytes, its absolute value must be less
 408  *             than the used buffer size or the returned pointer will
 409  *             point outside to the buffer data.
 410  *             The used buffer size can be checked with av_fifo_size().
 411  * @deprecated use the new AVFifo-API with av_fifo_peek() or av_fifo_peek_to_cb()
 412  */
 413 attribute_deprecated
 414 static inline uint8_t *av_fifo_peek2(const AVFifoBuffer *f, int offs)
 415 {
 416     uint8_t *ptr = f->rptr + offs;
 417     if (ptr >= f->end)
 418         ptr = f->buffer + (ptr - f->end);
 419     else if (ptr < f->buffer)
 420         ptr = f->end - (f->buffer - ptr);
 421     return ptr;
 422 }
 423 #endif
 424 #endif
 425
 426 #endif /* AVUTIL_FIFO_H */