From patchwork Wed Jun 5 13:18:08 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 49584 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:d792:0:b0:460:55fa:d5ed with SMTP id db18csp380850vqb; Wed, 5 Jun 2024 06:18:25 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCUqLjNFDNp7J/0nHnf6imj9CnZ8TccLRdErlbQMcIrrtbYBOBjC379WfmSZAh9y7rd1uFfX9QSbpbV7KHmI++pcqtOyUxysWkggFw== X-Google-Smtp-Source: AGHT+IGl9cWHn++Oquh/ZyOfUUFb2iIjEcMakfF2yh/dmVBcxfeJSYzavtWwiHxzq4yMkH7insm/ X-Received: by 2002:a50:9998:0:b0:578:4313:df10 with SMTP id 4fb4d7f45d1cf-57a8bc907d9mr1831991a12.31.1717593505609; Wed, 05 Jun 2024 06:18:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1717593505; cv=none; d=google.com; s=arc-20160816; b=NPw/ZlLFNj01cFdSO6V2lpUNYCaohN6/R/E3+W3ryB+DN+PplFx5C8giLZV+EjhEga PZOBiMT2o7KJrh/qBnE6R0WKPN11yQ9AHnQTOUOR5KcUhtUCWS6lnBVygI/a+vsYrfxj Qse18ySyAFe8e+8uHPUjtKHl6KZE/IBY7Q/i/qnVOnEP93W4GDZkm4dp1Pzp9xRYM3vn xhFnhj7PE35VeV/smkMTNlr8v7NMm7olMvkR/rfAndReqs+kexKl3oVF994bgsky2EeK r7uZG9EeUvMYDYbXT5EeMkUh+/raknx96cQP2pJCLkxQxRBi6ZCWpqbk8DIksKkgfX81 v5XA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:message-id:date:to:from :delivered-to; bh=ImPIiPQNNTXl6S32Zubuo9OVaCO9GG9eLrGIG2X16kk=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=kLgzjJdfdh4SV7iiBdlxm3SRJDKns1o3sT4uabHwZfUDUvF4Kuk6Z9QCga7akiXqrV rIhOcwX5ckgyYBAExGIFOvP7DbpYnnyhm8s2mypo4npm1TJlfvIOxQ1rGAEJvNboOvMn pncyY7qq8oUEmnNhpA6bM/brQXR6C3Olh7pSWkV7xXdN3TFp1E6JgUUZXaZddikUaOTr rZeaPXCJuVgaUeB8dq2NOx3xgMgVNMP3ztVSKhN08W8DVxLS7R+nQDF6PYXDeEO28LnL gAsM3gzWsyUAwSwc7lGIwltB5Ly+df4ctgcvpSV97msXJ5tlQQP3WJe7F5+FApoOZ7sa GItA==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id 4fb4d7f45d1cf-57a31cc7649si6115333a12.622.2024.06.05.06.18.20; Wed, 05 Jun 2024 06:18:25 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 66D3168D6BA; Wed, 5 Jun 2024 16:18:17 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: CjSv4ovLxypv 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