[FFmpeg-devel] [PATCH v6 2/4] lavu: Clarify relationship between AVClass, AVOption and context

[Stefano Sabatini]

On date Tuesday 2024-06-04 15:47:22 +0100, Andrew Sayers wrote:
> ---
>  libavutil/log.h | 16 +++++++++++++---
>  libavutil/opt.h | 26 +++++++++++++++++++++-----
>  2 files changed, 34 insertions(+), 8 deletions(-)
> 
> diff --git a/libavutil/log.h b/libavutil/log.h
> index ab7ceabe22..88b35897c6 100644
> --- a/libavutil/log.h
> +++ b/libavutil/log.h
> @@ -59,9 +59,19 @@ typedef enum {
>  struct AVOptionRanges;
>  
>  /**
> - * Describe the class of an AVClass context structure. That is an
> - * arbitrary struct of which the first field is a pointer to an
> - * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.).

> + * Generic Logging facilities and configuration options

Generic logging and options handling facilities.

> + *
> + * Logging and AVOptions functions expect to be passed structs

Logging and options handling functions ...

> + * whose first member is a pointer-to- at ref AVClass.
> + *

> + * Structs that only use logging facilities are often referred to as
> + * "AVClass context structures", while those that provide configuration
> + * options are called "AVOptions-enabled structs".

A struct with an AVClass as its first member can be used for both
logging and options management, there is no difference between the
two. My take:
|Structs that use AVClass might be referred to as AVClass
|contexts/structures, those that in addition define options might be
|called AVOptions contexts/structures.

> + *
> + * @see
> + * * @ref lavu_log
> + * * @ref avoptions
> + * * @ref Context
>   */
>  typedef struct AVClass {
>      /**
> diff --git a/libavutil/opt.h b/libavutil/opt.h
> index 07e27a9208..cdee8f7d28 100644
> --- a/libavutil/opt.h
> +++ b/libavutil/opt.h
> @@ -39,9 +39,16 @@
>   * @defgroup avoptions AVOptions
>   * @ingroup lavu_data
>   * @{
> - * AVOptions provide a generic system to declare options on arbitrary structs
> - * ("objects"). An option can have a help text, a type and a range of possible
> - * values. Options may then be enumerated, read and written to.
> + *
> + * Inspection and configuration for AVClass context structures
> + *
> + * Provides a generic API to declare and manage options on any struct
> + * whose first member is a pointer-to- at ref AVClass.  Structs with private
> + * contexts can use that AVClass to return further @ref AVClass "AVClass"es
> + * that allow access to options in the private structs.
> + *
> + * Each option can have a help text, a type and a range of possible values.
> + * Options may be enumerated, read and written to.
>   *
>   * There are two modes of access to members of AVOption and its child structs.
>   * One is called 'native access', and refers to access from the code that
> @@ -53,11 +60,20 @@
>   * question is allowed to access the field. This allows us to extend the
>   * semantics of those fields without breaking API compatibility.
>   *

> + * Note that AVOptions is not reentrant, and that many FFmpeg functions access

... AVOptions access is not reeentrant ...

> + * options from separate threads.  Unless otherwise indicated, it is best to
> + * avoid modifying options once a struct has been initialized.

But this note is not relevant to the change, and should probably be
discussed separately

[...]