From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id F26074B420 for ; Wed, 5 Jun 2024 13:18:19 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 2C23768D6B4; Wed, 5 Jun 2024 16:18:17 +0300 (EEST) Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D627968D630 for ; Wed, 5 Jun 2024 16:18:10 +0300 (EEST) Received: from 0.b.4.b.7.4.0.8.c.4.a.5.d.8.b.2.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:2b8d:5a4c:8047:b4b0] helo=andrews-2024-laptop.lan) by painless-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1sEqWn-008nLG-2V; Wed, 05 Jun 2024 14:18:10 +0100 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Wed, 5 Jun 2024 14:18:08 +0100 Message-ID: <20240605131808.282394-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.45.1 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH] lavu/opt: Mention that AVOptions is not reentrant X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Andrew Sayers Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: An external API developer might think they can use AVOptions to modify values during playback (e.g. putting a playback quality slider next to the volume slider). Make it clear that behaviour is not recommended. Include the warning in the group description and the text for every function that sets options, but leave it implicit in functions that get options. This reflects the fact that *modifying* options is likely to cause weird bugs, while *reading* options isn't guaranteed but is likely to be safe. --- libavutil/opt.h | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/libavutil/opt.h b/libavutil/opt.h index 07e27a9208..13292c6473 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -53,11 +53,16 @@ * question is allowed to access the field. This allows us to extend the * semantics of those fields without breaking API compatibility. * + * Note that AVOptions functions are not reentrant, and options may be accessed + * from internal FFmpeg threads. Unless otherwise noted, it is best to avoid + * modifying options once a struct has been initialized. + * * @section avoptions_scope Scope of AVOptions * * AVOptions is designed to support any set of multimedia configuration options - * that can be defined at compile-time. Although it is mainly used to expose - * FFmpeg options, you are welcome to adapt it to your own use case. + * that can be defined at compile-time and set at object creation time. Although + * it is mainly used to expose FFmpeg options, you are welcome to adapt it + * to your own use case. * * No single approach can ever fully solve the problem of configuration, * but please submit a patch if you believe you have found a problem @@ -483,6 +488,9 @@ typedef struct AVOptionRanges { /** * Set the values of all AVOption fields to their default values. * + * Note: like all AVOptions functions, this is not reentrant. Unless + * otherwise noted, it should only be used before initializing the struct. + * * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass) */ void av_opt_set_defaults(void *s); @@ -492,6 +500,9 @@ void av_opt_set_defaults(void *s); * AVOption fields for which (opt->flags & mask) == flags will have their * default applied to s. * + * Note: like all AVOptions functions, this is not reentrant. Unless + * otherwise noted, it should only be used before initializing the struct. + * * @param s an AVOption-enabled struct (its first member must be a pointer to AVClass) * @param mask combination of AV_OPT_FLAG_* * @param flags combination of AV_OPT_FLAG_* @@ -661,6 +672,9 @@ enum { * key. ctx must be an AVClass context, storing is done using * AVOptions. * + * Note: like all AVOptions functions, this is not reentrant. Unless + * otherwise noted, it should only be used before initializing the struct. + * * @param opts options string to parse, may be NULL * @param key_val_sep a 0-terminated list of characters used to * separate key from value @@ -679,6 +693,9 @@ int av_set_options_string(void *ctx, const char *opts, * Parse the key-value pairs list in opts. For each key=value pair found, * set the value of the corresponding option in ctx. * + * Note: like all AVOptions functions, this is not reentrant. Unless + * otherwise noted, it should only be used before initializing the struct. + * * @param ctx the AVClass object to set options on * @param opts the options string, key-value pairs separated by a * delimiter @@ -709,6 +726,9 @@ int av_opt_set_from_string(void *ctx, const char *opts, /** * Set all the options from a given dictionary on an object. * + * Note: like all AVOptions functions, this is not reentrant. Unless + * otherwise noted, it should only be used before initializing the struct. + * * @param obj a struct whose first element is a pointer to AVClass * @param options options to process. This dictionary will be freed and replaced * by a new one containing all options not found in obj. @@ -726,6 +746,9 @@ int av_opt_set_dict(void *obj, struct AVDictionary **options); /** * Set all the options from a given dictionary on an object. * + * Note: like all AVOptions functions, this is not reentrant. Unless + * otherwise noted, it should only be used before initializing the struct. + * * @param obj a struct whose first element is a pointer to AVClass * @param options options to process. This dictionary will be freed and replaced * by a new one containing all options not found in obj. @@ -764,6 +787,9 @@ int av_opt_copy(void *dest, const void *src); * @{ * Those functions set the field of obj with the given name to value. * + * Note: like all AVOptions functions, these are not reentrant. Unless + * otherwise noted, they should only be used before initializing the struct. + * * @param[in] obj A struct whose first element is a pointer to an AVClass. * @param[in] name the name of the field to set * @param[in] val The value to set. In case of av_opt_set() if the field is not -- 2.45.1 _______________________________________________ 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".