fftools/thread_queue.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 #ifndef FFTOOLS_THREAD_QUEUE_H
  20 #define FFTOOLS_THREAD_QUEUE_H
  21
  22 #include <string.h>
  23
  24 enum ThreadQueueType {
  25     THREAD_QUEUE_FRAMES,
  26     THREAD_QUEUE_PACKETS,
  27 };
  28
  29 typedef struct ThreadQueue ThreadQueue;
  30
  31 /**
  32  * Allocate a queue for sending data between threads.
  33  *
  34  * @param nb_streams number of streams for which a distinct EOF state is
  35  *                   maintained
  36  * @param queue_size number of items that can be stored in the queue without
  37  *                   blocking
  38  */
  39 ThreadQueue *tq_alloc(unsigned int nb_streams, size_t queue_size,
  40                       enum ThreadQueueType type);
  41 void         tq_free(ThreadQueue **tq);
  42
  43 /**
  44  * Send an item for the given stream to the queue.
  45  *
  46  * @param data the item to send, its contents will be moved using the callback
  47  *             provided to tq_alloc(); on failure the item will be left
  48  *             untouched
  49  * @return
  50  * - 0 the item was successfully sent
  51  * - AVERROR(ENOMEM) could not allocate an item for writing to the FIFO
  52  * - AVERROR(EINVAL) the sending side has previously been marked as finished
  53  * - AVERROR_EOF the receiving side has marked the given stream as finished
  54  */
  55 int tq_send(ThreadQueue *tq, unsigned int stream_idx, void *data);
  56 /**
  57  * Mark the given stream finished from the sending side.
  58  */
  59 void tq_send_finish(ThreadQueue *tq, unsigned int stream_idx);
  60
  61 /**
  62  * Prevent further reads from the thread queue until it is unchoked. Threads
  63  * attempting to read from the queue will block, similar to when the queue is
  64  * empty.
  65  *
  66  * @param choked 1 to choke, 0 to unchoke
  67  */
  68 void tq_choke(ThreadQueue *tq, int choked);
  69
  70 /**
  71  * Read the next item from the queue.
  72  *
  73  * @param stream_idx the index of the stream that was processed or -1 will be
  74  *                   written here
  75  * @param data the data item will be written here on success using the
  76  *             callback provided to tq_alloc()
  77  * @return
  78  * - 0 a data item was successfully read; *stream_idx contains a non-negative
  79  *   stream index
  80  * - AVERROR_EOF When *stream_idx is non-negative, this signals that the sending
  81  *   side has marked the given stream as finished. This will happen at most once
  82  *   for each stream. When *stream_idx is -1, all streams are done.
  83  */
  84 int tq_receive(ThreadQueue *tq, int *stream_idx, void *data);
  85 /**
  86  * Mark the given stream finished from the receiving side.
  87  */
  88 void tq_receive_finish(ThreadQueue *tq, unsigned int stream_idx);
  89
  90 #endif // FFTOOLS_THREAD_QUEUE_H