[FFmpeg-devel,v2,01/27] avcodec/threadprogress: Add new API for frame-threaded progress

The API is similar to the ThreadFrame API, with the exception
that it no longer has an included AVFrame and that it has its
own mutexes and condition variables which makes it more independent
of pthread_frame.c. One can wait on anything via a ThreadProgress.
One just has to ensure that the lifetime of the object containing
the ThreadProgress is long enough. This will typically be solved
by putting a ThreadProgress in a refcounted structure that is
shared between threads.

Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
---
Now including its own mutex and condition variable. Hopefully
no system has constraints on the number of mutexes and condition
variables it supports.

 libavcodec/threadprogress.c | 73 +++++++++++++++++++++++++++++
 libavcodec/threadprogress.h | 91 +++++++++++++++++++++++++++++++++++++
 2 files changed, 164 insertions(+)
 create mode 100644 libavcodec/threadprogress.c
 create mode 100644 libavcodec/threadprogress.h

Quoting Andreas Rheinhardt (2024-04-08 21:51:59)
> +/**
> + * ThreadProgress is an API to easily notify other threads about progress
> + * of any kind as long as it can be packaged into an int and is consistent
> + * with the natural ordering of integers.
> + *
> + * Each initialized ThreadProgress can be in one of two modes: No-op mode
> + * or ordinary mode. In the former mode, ff_thread_report_progress() and
> + * ff_thread_await_progress() are no-ops to simply support usecases like
> + * non-frame-threading. Only in the latter case perform these functions

Maybe 'strictly serial usecases' or 'non-parallel usecases' would sound
better.

> + * what their name already implies.
> + */
> +
> +#include <limits.h>
> +#include <stdatomic.h>
> +#include "libavutil/thread.h"
> +
> +/**
> + * This struct should be treated as opaque by users.
> + */
> +typedef struct ThreadProgress {
> +    atomic_int progress;
> +    unsigned   init;
> +    AVMutex progress_mutex;
> +    AVCond  progress_cond;
> +} ThreadProgress;
> +
> +/**
> + * Initialize a ThreadProgress.
> + *
> + * @param init_mode If zero, the ThreadProgress will be initialized so that
> + *                  to be in no-op mode as described above. Otherwise

Seems like something missing here.

LGTM otherwise.

Andreas Rheinhardt:
> The API is similar to the ThreadFrame API, with the exception
> that it no longer has an included AVFrame and that it has its
> own mutexes and condition variables which makes it more independent
> of pthread_frame.c. One can wait on anything via a ThreadProgress.
> One just has to ensure that the lifetime of the object containing
> the ThreadProgress is long enough. This will typically be solved
> by putting a ThreadProgress in a refcounted structure that is
> shared between threads.
> 
> Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
> ---
> Now including its own mutex and condition variable. Hopefully
> no system has constraints on the number of mutexes and condition
> variables it supports.
> 
>  libavcodec/threadprogress.c | 73 +++++++++++++++++++++++++++++
>  libavcodec/threadprogress.h | 91 +++++++++++++++++++++++++++++++++++++
>  2 files changed, 164 insertions(+)
>  create mode 100644 libavcodec/threadprogress.c
>  create mode 100644 libavcodec/threadprogress.h
> 
> diff --git a/libavcodec/threadprogress.c b/libavcodec/threadprogress.c
> new file mode 100644
> index 0000000000..dd2a4d2336
> --- /dev/null
> +++ b/libavcodec/threadprogress.c
> @@ -0,0 +1,73 @@
> +/*
> + * Copyright (c) 2022 Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
> + *
> + * 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 <limits.h>
> +#include <stdatomic.h>
> +
> +#include "pthread_internal.h"
> +#include "threadprogress.h"
> +#include "libavutil/attributes.h"
> +
> +DEFINE_OFFSET_ARRAY(ThreadProgress, thread_progress, init,
> +                    (offsetof(ThreadProgress, progress_mutex)),
> +                    (offsetof(ThreadProgress, progress_cond)));
> +
> +av_cold int ff_thread_progress_init(ThreadProgress *pro, int init_mode)
> +{
> +    atomic_init(&pro->progress, init_mode ? -1 : INT_MAX);
> +    if (!init_mode) {
> +        pro->init = 0;
> +        return 0;
> +    }
> +    return ff_pthread_init(pro, thread_progress_offsets);
> +}
> +
> +av_cold void ff_thread_progress_destroy(ThreadProgress *pro)
> +{
> +    ff_pthread_free(pro, thread_progress_offsets);
> +}
> +
> +void ff_thread_progress_report(ThreadProgress *pro, int n)
> +{
> +    if (atomic_load_explicit(&pro->progress, memory_order_relaxed) >= n)
> +        return;
> +
> +    atomic_store_explicit(&pro->progress, n, memory_order_release);
> +
> +    pthread_mutex_lock(&pro->progress_mutex);
> +    pthread_cond_broadcast(&pro->progress_cond);
> +    pthread_mutex_unlock(&pro->progress_mutex);
> +}
> +
> +void ff_thread_progress_await(const ThreadProgress *pro_c, int n)
> +{
> +    /* Casting const away here is safe, because we only read from progress
> +     * and will leave pro_c in the same state upon leaving the function
> +     * as it had at the beginning. */
> +    ThreadProgress *pro = (ThreadProgress*)pro_c;
> +
> +    if (atomic_load_explicit(&pro->progress, memory_order_acquire) >= n)
> +        return;
> +
> +    pthread_mutex_lock(&pro->progress_mutex);
> +    while (atomic_load_explicit(&pro->progress, memory_order_relaxed) < n)
> +        pthread_cond_wait(&pro->progress_cond, &pro->progress_mutex);
> +    pthread_mutex_unlock(&pro->progress_mutex);
> +}
> diff --git a/libavcodec/threadprogress.h b/libavcodec/threadprogress.h
> new file mode 100644
> index 0000000000..786802cbf1
> --- /dev/null
> +++ b/libavcodec/threadprogress.h
> @@ -0,0 +1,91 @@
> +/*
> + * Copyright (c) 2022 Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
> + *
> + * 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 AVCODEC_THREADPROGRESS_H
> +#define AVCODEC_THREADPROGRESS_H
> +
> +/**
> + * ThreadProgress is an API to easily notify other threads about progress
> + * of any kind as long as it can be packaged into an int and is consistent
> + * with the natural ordering of integers.
> + *
> + * Each initialized ThreadProgress can be in one of two modes: No-op mode
> + * or ordinary mode. In the former mode, ff_thread_report_progress() and
> + * ff_thread_await_progress() are no-ops to simply support usecases like
> + * non-frame-threading. Only in the latter case perform these functions
> + * what their name already implies.
> + */
> +
> +#include <limits.h>
> +#include <stdatomic.h>
> +#include "libavutil/thread.h"
> +
> +/**
> + * This struct should be treated as opaque by users.
> + */
> +typedef struct ThreadProgress {
> +    atomic_int progress;
> +    unsigned   init;
> +    AVMutex progress_mutex;
> +    AVCond  progress_cond;
> +} ThreadProgress;
> +
> +/**
> + * Initialize a ThreadProgress.
> + *
> + * @param init_mode If zero, the ThreadProgress will be initialized so that
> + *                  to be in no-op mode as described above. Otherwise
> + */
> +int ff_thread_progress_init(ThreadProgress *pro, int init_mode);
> +
> +/**
> + * Destroy a ThreadProgress. Can be called on a ThreadProgress that
> + * has never been initialized provided that the ThreadProgress struct
> + * has been initially zeroed. Must be called even if ff_thread_progress_init()
> + * failed.
> + */
> +void ff_thread_progress_destroy(ThreadProgress *pro);
> +
> +/**
> + * Reset the ThreadProgress's progress progress counter; must only be called
> + * if it is not in use in any way (e.g. no thread may wait on it via
> + * ff_thread_progress_await()).
> + */
> +static inline void ff_thread_progress_reset(ThreadProgress *pro)
> +{
> +    atomic_init(&pro->progress, pro->init ? -1 : INT_MAX);
> +}
> +
> +/**
> + * This function is a no-op in no-op mode; otherwise it notifies
> + * other threads that a certain level of progress has been reached.
> + * Later calls with lower values of progress have no effect.
> + */
> +void ff_thread_progress_report(ThreadProgress *pro, int progress);
> +
> +/**
> + * This function is a no-op in no-op mode; otherwise it waits
> + * until other threads have reached a certain level of progress:
> + * This function will return after another thread has called
> + * ff_thread_progress_report() with the same or higher value for progress.
> + */
> +void ff_thread_progress_await(const ThreadProgress *pro, int progress);
> +
> +#endif /* AVCODEC_THREADPROGRESS_H */

Will apply this patchset tomorrow unless there are objections.

- Andreas

On 18 Apr 2024, at 22:40, Andreas Rheinhardt wrote:

> Andreas Rheinhardt:
>> The API is similar to the ThreadFrame API, with the exception
>> that it no longer has an included AVFrame and that it has its
>> own mutexes and condition variables which makes it more independent
>> of pthread_frame.c. One can wait on anything via a ThreadProgress.
>> One just has to ensure that the lifetime of the object containing
>> the ThreadProgress is long enough. This will typically be solved
>> by putting a ThreadProgress in a refcounted structure that is
>> shared between threads.
>>
>> Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
>> ---
>> Now including its own mutex and condition variable. Hopefully
>> no system has constraints on the number of mutexes and condition
>> variables it supports.
>>
>>  libavcodec/threadprogress.c | 73 +++++++++++++++++++++++++++++
>>  libavcodec/threadprogress.h | 91 +++++++++++++++++++++++++++++++++++++
>>  2 files changed, 164 insertions(+)
>>  create mode 100644 libavcodec/threadprogress.c
>>  create mode 100644 libavcodec/threadprogress.h
>>
>> diff --git a/libavcodec/threadprogress.c b/libavcodec/threadprogress.c
>> new file mode 100644
>> index 0000000000..dd2a4d2336
>> --- /dev/null
>> +++ b/libavcodec/threadprogress.c
>> @@ -0,0 +1,73 @@
>> +/*
>> + * Copyright (c) 2022 Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
>> + *
>> + * 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 <limits.h>
>> +#include <stdatomic.h>
>> +
>> +#include "pthread_internal.h"
>> +#include "threadprogress.h"
>> +#include "libavutil/attributes.h"
>> +
>> +DEFINE_OFFSET_ARRAY(ThreadProgress, thread_progress, init,
>> +                    (offsetof(ThreadProgress, progress_mutex)),
>> +                    (offsetof(ThreadProgress, progress_cond)));
>> +
>> +av_cold int ff_thread_progress_init(ThreadProgress *pro, int init_mode)
>> +{
>> +    atomic_init(&pro->progress, init_mode ? -1 : INT_MAX);
>> +    if (!init_mode) {
>> +        pro->init = 0;
>> +        return 0;
>> +    }
>> +    return ff_pthread_init(pro, thread_progress_offsets);
>> +}
>> +
>> +av_cold void ff_thread_progress_destroy(ThreadProgress *pro)
>> +{
>> +    ff_pthread_free(pro, thread_progress_offsets);
>> +}
>> +
>> +void ff_thread_progress_report(ThreadProgress *pro, int n)
>> +{
>> +    if (atomic_load_explicit(&pro->progress, memory_order_relaxed) >= n)
>> +        return;
>> +
>> +    atomic_store_explicit(&pro->progress, n, memory_order_release);
>> +
>> +    pthread_mutex_lock(&pro->progress_mutex);
>> +    pthread_cond_broadcast(&pro->progress_cond);
>> +    pthread_mutex_unlock(&pro->progress_mutex);
>> +}
>> +
>> +void ff_thread_progress_await(const ThreadProgress *pro_c, int n)
>> +{
>> +    /* Casting const away here is safe, because we only read from progress
>> +     * and will leave pro_c in the same state upon leaving the function
>> +     * as it had at the beginning. */
>> +    ThreadProgress *pro = (ThreadProgress*)pro_c;
>> +
>> +    if (atomic_load_explicit(&pro->progress, memory_order_acquire) >= n)
>> +        return;
>> +
>> +    pthread_mutex_lock(&pro->progress_mutex);
>> +    while (atomic_load_explicit(&pro->progress, memory_order_relaxed) < n)
>> +        pthread_cond_wait(&pro->progress_cond, &pro->progress_mutex);
>> +    pthread_mutex_unlock(&pro->progress_mutex);
>> +}
>> diff --git a/libavcodec/threadprogress.h b/libavcodec/threadprogress.h
>> new file mode 100644
>> index 0000000000..786802cbf1
>> --- /dev/null
>> +++ b/libavcodec/threadprogress.h
>> @@ -0,0 +1,91 @@
>> +/*
>> + * Copyright (c) 2022 Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
>> + *
>> + * 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 AVCODEC_THREADPROGRESS_H
>> +#define AVCODEC_THREADPROGRESS_H
>> +
>> +/**
>> + * ThreadProgress is an API to easily notify other threads about progress
>> + * of any kind as long as it can be packaged into an int and is consistent
>> + * with the natural ordering of integers.
>> + *
>> + * Each initialized ThreadProgress can be in one of two modes: No-op mode
>> + * or ordinary mode. In the former mode, ff_thread_report_progress() and
>> + * ff_thread_await_progress() are no-ops to simply support usecases like
>> + * non-frame-threading. Only in the latter case perform these functions
>> + * what their name already implies.
>> + */
>> +
>> +#include <limits.h>
>> +#include <stdatomic.h>
>> +#include "libavutil/thread.h"
>> +
>> +/**
>> + * This struct should be treated as opaque by users.
>> + */
>> +typedef struct ThreadProgress {
>> +    atomic_int progress;
>> +    unsigned   init;
>> +    AVMutex progress_mutex;
>> +    AVCond  progress_cond;
>> +} ThreadProgress;
>> +
>> +/**
>> + * Initialize a ThreadProgress.
>> + *
>> + * @param init_mode If zero, the ThreadProgress will be initialized so that
>> + *                  to be in no-op mode as described above. Otherwise

Nit: Stray „Otherwise“ here at the end?

>> + */
>> +int ff_thread_progress_init(ThreadProgress *pro, int init_mode);
>> +
>> +/**
>> + * Destroy a ThreadProgress. Can be called on a ThreadProgress that
>> + * has never been initialized provided that the ThreadProgress struct
>> + * has been initially zeroed. Must be called even if ff_thread_progress_init()
>> + * failed.
>> + */
>> +void ff_thread_progress_destroy(ThreadProgress *pro);
>> +
>> +/**
>> + * Reset the ThreadProgress's progress progress counter; must only be called

I think you can use a proper reference here: ::ThreadProgress.progress

>> + * if it is not in use in any way (e.g. no thread may wait on it via
>> + * ff_thread_progress_await()).
>> + */
>> +static inline void ff_thread_progress_reset(ThreadProgress *pro)
>> +{
>> +    atomic_init(&pro->progress, pro->init ? -1 : INT_MAX);
>> +}
>> +
>> +/**
>> + * This function is a no-op in no-op mode; otherwise it notifies
>> + * other threads that a certain level of progress has been reached.
>> + * Later calls with lower values of progress have no effect.
>> + */
>> +void ff_thread_progress_report(ThreadProgress *pro, int progress);
>> +
>> +/**
>> + * This function is a no-op in no-op mode; otherwise it waits
>> + * until other threads have reached a certain level of progress:
>> + * This function will return after another thread has called
>> + * ff_thread_progress_report() with the same or higher value for progress.
>> + */
>> +void ff_thread_progress_await(const ThreadProgress *pro, int progress);
>> +
>> +#endif /* AVCODEC_THREADPROGRESS_H */
>
> Will apply this patchset tomorrow unless there are objections.
>
> - Andreas
>
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".