[FFmpeg-devel,3/4] lavfi: add FFFrameQueue API.

Signed-off-by: Nicolas George <george@nsup.org>
---
 libavfilter/Makefile     |   1 +
 libavfilter/framequeue.c | 123 +++++++++++++++++++++++++++++++++
 libavfilter/framequeue.h | 173 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 297 insertions(+)
 create mode 100644 libavfilter/framequeue.c
 create mode 100644 libavfilter/framequeue.h

On Sun, 23 Oct 2016 12:27:41 +0200
Nicolas George <george@nsup.org> wrote:

> Signed-off-by: Nicolas George <george@nsup.org>
> ---
>  libavfilter/Makefile     |   1 +
>  libavfilter/framequeue.c | 123 +++++++++++++++++++++++++++++++++
>  libavfilter/framequeue.h | 173 +++++++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 297 insertions(+)
>  create mode 100644 libavfilter/framequeue.c
>  create mode 100644 libavfilter/framequeue.h
> 
> diff --git a/libavfilter/Makefile b/libavfilter/Makefile
> index 7ed4696..623dd8e 100644
> --- a/libavfilter/Makefile
> +++ b/libavfilter/Makefile
> @@ -18,6 +18,7 @@ OBJS = allfilters.o                                                     \
>         fifo.o                                                           \
>         formats.o                                                        \
>         framepool.o                                                      \
> +       framequeue.o                                                     \
>         graphdump.o                                                      \
>         graphparser.o                                                    \
>         opencl_allkernels.o                                              \
> diff --git a/libavfilter/framequeue.c b/libavfilter/framequeue.c
> new file mode 100644
> index 0000000..debeab2
> --- /dev/null
> +++ b/libavfilter/framequeue.c
> @@ -0,0 +1,123 @@
> +/*
> + * Generic frame queue
> + * Copyright (c) 2016 Nicolas George
> + *
> + * This file is part of FFmpeg.
> + *
> + * FFmpeg is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU Lesser General Public License
> + * as published by the Free Software Foundation; either
> + * version 2.1 of the License, or (at your option) any later version.
> + *
> + * FFmpeg is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> + * GNU Lesser General Public License for more details.
> + *
> + * You should have received a copy of the GNU Lesser General Public License
> + * along with FFmpeg; if not, write to the Free Software Foundation, Inc.,
> + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
> + */
> +
> +#include "libavutil/avassert.h"
> +#include "framequeue.h"
> +
> +static inline FFFrameBucket *bucket(FFFrameQueue *fq, size_t idx)
> +{
> +    return &fq->queue[(fq->tail + idx) & (fq->allocated - 1)];
> +}
> +
> +void ff_framequeue_global_init(FFFrameQueueGlobal *fqg)
> +{
> +}
> +
> +static void check_consistency(FFFrameQueue *fq)
> +{
> +#if ASSERT_LEVEL >= 2
> +    uint64_t nb_samples = 0;
> +    size_t i;
> +
> +    av_assert0(fq->queued == fq->total_frames_head - fq->total_frames_tail);
> +    for (i = 0; i < fq->queued; i++)
> +        nb_samples += bucket(fq, i)->frame->nb_samples;
> +    av_assert0(nb_samples == fq->total_samples_head - fq->total_samples_tail);
> +#endif
> +}
> +
> +void ff_framequeue_init(FFFrameQueue *fq, FFFrameQueueGlobal *fqg)
> +{
> +    fq->queue = &fq->first_bucket;
> +    fq->allocated = 1;
> +}
> +
> +void ff_framequeue_free(FFFrameQueue *fq)
> +{
> +    while (fq->queued) {
> +        AVFrame *frame = ff_framequeue_take(fq);
> +        av_frame_free(&frame);
> +    }
> +    if (fq->queue != &fq->first_bucket)
> +        av_freep(&fq->queue);
> +}
> +
> +int ff_framequeue_add(FFFrameQueue *fq, AVFrame *frame)
> +{
> +    FFFrameBucket *b;
> +
> +    check_consistency(fq);
> +    if (fq->queued == fq->allocated) {
> +        if (fq->allocated == 1) {
> +            size_t na = 8;
> +            FFFrameBucket *nq = av_realloc_array(NULL, na, sizeof(*nq));
> +            if (!nq)
> +                return AVERROR(ENOMEM);
> +            nq[0] = fq->queue[0];
> +            fq->queue = nq;
> +            fq->allocated = na;
> +        } else {
> +            size_t na = fq->allocated << 1;
> +            FFFrameBucket *nq = av_realloc_array(fq->queue, na, sizeof(*nq));
> +            if (!nq)
> +                return AVERROR(ENOMEM);
> +            if (fq->tail + fq->queued > fq->allocated)
> +                memmove(nq + fq->allocated, nq,
> +                        (fq->tail + fq->queued - fq->allocated) * sizeof(*nq));
> +            fq->queue = nq;
> +            fq->allocated = na;
> +        }
> +    }
> +    b = bucket(fq, fq->queued);
> +    b->frame = frame;
> +    fq->queued++;
> +    fq->total_frames_head++;
> +    fq->total_samples_head += frame->nb_samples;
> +    check_consistency(fq);
> +    return 0;
> +}
> +
> +AVFrame *ff_framequeue_take(FFFrameQueue *fq)
> +{
> +    FFFrameBucket *b;
> +
> +    check_consistency(fq);
> +    av_assert1(fq->queued);
> +    b = bucket(fq, 0);
> +    fq->queued--;
> +    fq->tail++;
> +    fq->tail &= fq->allocated - 1;
> +    fq->total_frames_tail++;
> +    fq->total_samples_tail += b->frame->nb_samples;
> +    check_consistency(fq);
> +    return b->frame;
> +}
> +
> +AVFrame *ff_framequeue_peek(FFFrameQueue *fq, size_t idx)
> +{
> +    FFFrameBucket *b;
> +
> +    check_consistency(fq);
> +    av_assert1(idx < fq->queued);
> +    b = bucket(fq, idx);
> +    check_consistency(fq);
> +    return b->frame;
> +}
> diff --git a/libavfilter/framequeue.h b/libavfilter/framequeue.h
> new file mode 100644
> index 0000000..558ea22
> --- /dev/null
> +++ b/libavfilter/framequeue.h
> @@ -0,0 +1,173 @@
> +/*
> + * Generic frame queue
> + * Copyright (c) 2016 Nicolas George
> + *
> + * This file is part of FFmpeg.
> + *
> + * FFmpeg is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU Lesser General Public License
> + * as published by the Free Software Foundation; either
> + * version 2.1 of the License, or (at your option) any later version.
> + *
> + * FFmpeg is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> + * GNU Lesser General Public License for more details.
> + *
> + * You should have received a copy of the GNU Lesser General Public License
> + * along with FFmpeg; if not, write to the Free Software Foundation, Inc.,
> + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
> + */
> +
> +#ifndef AVFILTER_FRAMEQUEUE_H
> +#define AVFILTER_FRAMEQUEUE_H
> +
> +/**
> + * FFFrameQueue: simple AVFrame queue API
> + *
> + * Note: this API is not thread-safe. Concurrent access to the same queue
> + * must be protected by a mutex or any synchronization mechanism.
> + */
> +
> +#include "libavutil/frame.h"
> +
> +typedef struct FFFrameBucket {
> +    AVFrame *frame;
> +} FFFrameBucket;
> +
> +/**
> + * Structure to hold global options and statistics for frame queues.
> + *
> + * This structure is intended to allow implementing global control of the
> + * frame queues, including memory consumption caps.
> + *
> + * It is currently empty.
> + */
> +typedef struct FFFrameQueueGlobal {
> +} FFFrameQueueGlobal;
> +
> +/**
> + * Queue of AVFrame pointers.
> + */
> +typedef struct FFFrameQueue {
> +
> +    /**
> +     * Array of allocated buckets, used as a circular buffer.
> +     */
> +    FFFrameBucket *queue;
> +
> +    /**
> +     * Size of the array of buckets.
> +     */
> +    size_t allocated;
> +
> +    /**
> +     * Tail of the queue.
> +     * It is the index in the array of the next frame to take.
> +     */
> +    size_t tail;
> +
> +    /**
> +     * Number of currently queued frames.
> +     */
> +    size_t queued;
> +
> +    /**
> +     * Pre-allocated bucket for queues of size 1.
> +     */
> +    FFFrameBucket first_bucket;
> +
> +    /**
> +     * Total number of frames entered in the queue.
> +     */
> +    uint64_t total_frames_head;
> +
> +    /**
> +     * Total number of frames dequeued from the queue.
> +     * queued = total_frames_head - total_frames_tail
> +     */
> +    uint64_t total_frames_tail;
> +
> +    /**
> +     * Total number of samples entered in the queue.
> +     */
> +    uint64_t total_samples_head;
> +
> +    /**
> +     * Total number of samples dequeued from the queue.
> +     * queued_samples = total_samples_head - total_samples_tail
> +     */
> +    uint64_t total_samples_tail;
> +
> +} FFFrameQueue;
> +
> +/**
> + * Init a global structure.
> + */
> +void ff_framequeue_global_init(FFFrameQueueGlobal *fqg);
> +
> +/**
> + * Init a frame queue and attach it to a global structure.
> + */
> +void ff_framequeue_init(FFFrameQueue *fq, FFFrameQueueGlobal *fqg);
> +
> +/**
> + * Free the queue and all queued frames.
> + */
> +void ff_framequeue_free(FFFrameQueue *fq);
> +
> +/**
> + * Add a frame.
> + * @return  >=0 or an AVERROR code.
> + */
> +int ff_framequeue_add(FFFrameQueue *fq, AVFrame *frame);
> +
> +/**
> + * Take the first frame in the queue.
> + * Must not be used with empty queues.
> + */
> +AVFrame *ff_framequeue_take(FFFrameQueue *fq);
> +
> +/**
> + * Access a frame in the queue, without removing it.
> + * The first frame is numbered 0; the designated frame must exist.
> + */
> +AVFrame *ff_framequeue_peek(FFFrameQueue *fq, size_t idx);
> +
> +/**
> + * Get the number of queued frames.
> + */
> +static inline size_t ff_framequeue_queued_frames(const FFFrameQueue *fq)
> +{
> +    return fq->queued;
> +}
> +
> +/**
> + * Get the number of queued samples.
> + */
> +static inline uint64_t ff_framequeue_queued_samples(const FFFrameQueue *fq)
> +{
> +    return fq->total_samples_head - fq->total_samples_tail;
> +}
> +
> +/**
> + * Update the statistics after a frame accessed using ff_framequeue_peek()
> + * was modified.
> + * Currently used only as a marker.
> + */
> +static inline void ff_framequeue_update_peeked(FFFrameQueue *fq, size_t idx)
> +{
> +}
> +
> +/**
> + * Update the sample count in the queue.
> + *
> + * This function must be used when the first frame was accessed using
> + * ff_framequeue_peek() and samples were removed from it.
> + */
> +static inline void ff_framequeue_skip_samples(FFFrameQueue *fq, size_t n)
> +{
> +    fq->total_samples_tail += n;
> +}
> +
> +#endif /* AVFILTER_FRAMEQUEUE_H */

Is all this complexity really justified? This seems to do 2 things:
- implement a queue for O(1) addition/removal of items
- add some bookkeeping for audio frames (total sample count)

The former seems questionable - are there really going to be that many
frames in a queue that it pays? Why not just use an array? Or if really
needed, why not make a generic queue implementation?

The latter is a bit special and a bit of a leaky abstraction - the
frames can be updated without knowledge of the queue, and you have to
restore consistency manually by calling ff_framequeue_skip_samples()
(which works only for some specific scenario, like removing samples).