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 BD99B4986B for ; Sat, 20 Apr 2024 16:48:43 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 4CB3168D216; Sat, 20 Apr 2024 19:48:42 +0300 (EEST) Received: from mail-ej1-f52.google.com (mail-ej1-f52.google.com [209.85.218.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id AF34E688189 for ; Sat, 20 Apr 2024 19:48:35 +0300 (EEST) Received: by mail-ej1-f52.google.com with SMTP id a640c23a62f3a-a524ecaf215so325680466b.2 for ; Sat, 20 Apr 2024 09:48:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1713631714; x=1714236514; darn=ffmpeg.org; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date:from:to:cc :subject:date:message-id:reply-to; bh=cHSUKEilgxOPtQgLHI3OGlrtwcYgsU8r8Q+bLA2SEzY=; b=TZX6BVqwu1tdoECPayTpk+TL999La8mc7H7P5/Ywk78K0Ef4GOfcnj5nPsSlVXkTY2 5jhcqgH0XX+ZJ94XJIkkG/qCxdOPjNcACh8MaF4nOQ8wxBynoetItggfof3EGtkpszpB eoJd7HLKCapVXyXmqlPR2eZCvGCLdTSCn8h1u2w+2lkWEi9CbJcn292zR6LOwmju41zV iPQPWbpXDz9oe4DDndRN2sRreq5V6i+u3b0T93yFLGQyVWhm6mNz/lY5+BiNejp4cQE1 OsPkeKYY7UcGTFX4SrFYz8oz2rM1pL3c1bxXB+GFjs2mnNvzs28cmd5DOKzpuiCLPyYD SlRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713631714; x=1714236514; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=cHSUKEilgxOPtQgLHI3OGlrtwcYgsU8r8Q+bLA2SEzY=; b=isnG3yBoiz2yi/9AUEbR/dxw791mqPC5xi+YqJDJQ7XoGaUmL4UepTgQXRC0TvIQbZ J1kEXL5kQ78pe3k1rsMm7qEWdiH/9jeuY1LAbxdmPk2CnKBxLHGYxo33JPBCmuOTj5sb kq3pVDLkXznsmvjrzq58Zu60+yoQMhOcoH5VTouMsKkAVxAnGpzbG/AubEb+Z2KAts7d kfUZOq/daI5x/BHzwIuJv6UXr0Prxz8EFikGpdU2U/AucdyIZmuCMNM3MpQCgAxARzCp BGZU5sfEik6OuItDaJdvXbzmMRPeANy5OEjAgihUokAN4M+lvMwsdUQ6e4dWYTr03HXl /9rA== X-Gm-Message-State: AOJu0YwXT15Ke56bObdkgZgjbMdWLEOiPoOOcsP356x1F+A6hclJ+clr MgRnWduthreBLauoOhRsyFcwBmBZiG4jcdszBPy/ZXJakH4Rwg38EiuPrA== X-Google-Smtp-Source: AGHT+IFkV54AYCmAdfDkdT0Vts+Z4SWohv9f6mGPNDT9Vz06gFV6IK6N2ksdxGan39DDMExXjj663g== X-Received: by 2002:a17:906:6d05:b0:a55:653b:3981 with SMTP id m5-20020a1709066d0500b00a55653b3981mr3440492ejr.50.1713631713807; Sat, 20 Apr 2024 09:48:33 -0700 (PDT) Received: from mariano (host-87-17-49-61.retail.telecomitalia.it. [87.17.49.61]) by smtp.gmail.com with ESMTPSA id my45-20020a1709065a6d00b00a55a0e515a0sm582758ejc.48.2024.04.20.09.48.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 20 Apr 2024 09:48:33 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id 7740FBFCE8; Sat, 20 Apr 2024 18:48:32 +0200 (CEST) Date: Sat, 20 Apr 2024 18:48:32 +0200 From: Stefano Sabatini To: FFmpeg development discussions and patches Message-ID: Mail-Followup-To: FFmpeg development discussions and patches , Andrew Sayers References: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20240420121943.201032-1-ffmpeg-devel@pileofstuff.org> User-Agent: Mutt/2.1.4 (2021-12-11) Subject: Re: [FFmpeg-devel] [PATCH v2 1/3] doc: Explain what "context" means 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: On date Saturday 2024-04-20 13:19:41 +0100, Andrew Sayers wrote: > Based largely on the explanation by Stefano Sabatini: > https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325854.html > --- > doc/jargon.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 169 insertions(+) > create mode 100644 doc/jargon.md > > diff --git a/doc/jargon.md b/doc/jargon.md > new file mode 100644 > index 0000000000..f967b5c8bc > --- /dev/null > +++ b/doc/jargon.md > @@ -0,0 +1,169 @@ > +# Jargon > + > +Terms used throughout the code that developers may need to know. > + > +@anchor context > + > +## Context > + > +A design pattern that stores the context (e.g. configuration) for a series > +of operations in a "context" structure, and moves other information with > +a longer or shorter lifetime elsewhere. I'd skip the mention of a design pattern since this is about the jargon. So a simplified variant would be: A "context" is a a structure used to store information (e.g. configuration and/or internal state) for a series of operations working on the same data. > + > +Consider a code snippet to modify text then print it: > + > +```c > +/** > + * Contextual information about printing a series of messages > + */ > +struct ModifyThenPrintContext { > + > + /** > + * Members of the context usually are usually part of its public API... > + */ > + FILE *out; > + > + /** > + * ... but check the documentation just in case > + */ > + [[deprecated]] > + int no_longer_part_of_the_public_api; > + > + /** > + * The "internal context" is private to the context itself. > + * > + * Unlike the members above, the private context is not guaranteed > + * and can change arbitrarily between versions. > + */ > + void* priv_data; > +}; > + > +/** > + * Long-lifetime information, reused by many contexts > + */ > +enum ModifyThenPrintDialect { > + MODIFY_THEN_PRINT_PLAIN_TEXT, > + MODIFY_THEN_PRINT_REGEX, > + MODIFY_THEN_PRINT_REGEX_PCRE > +}; > + > +/** > + * Short-lifetime information, used repeatedly in a single context > + */ > +struct ModifyThenPrintMessage { > + char *str; > + char *replace_this; > + char *with_this; > +}; > + > +/** > + * Allocate and initialize a ModifyThenPrintContext > + * > + * This creates a new pointer, then fills in some sensible defaults. > + * > + * We can reasonably assume this function will initialise `priv_data` > + * with a dialect-specific object, but shouldn't make any assumptions > + * about what that object is. > + * > + */ > +int ModifyThenPrintContext_alloc_context(struct ModifyThenPrintContext **ctx, > + FILE *out, > + enum ModifyThenPrintDialect dialect); > + > +/** > + * Uninitialize and deallocate a ModifyThenPrintContext > + * > + * This does any work required by the private context in `priv_data` > + * (e.g. deallocating it), then deallocates the main context itself. > + * > + */ > +int ModifyThenPrintContext_free(struct ModifyThenPrintContext *ctx); > + > +/** > + * Print a single message > + */ > +int ModifyThenPrintContext_print(struct ModifyThenPrintContext *ctx, > + struct ModifyThenPrintMessage *msg); > + > +int print_hello_world() > +{ > + > + int ret = 0; > + > + struct ModifyThenPrintContext *ctx; > + > + struct ModifyThenPrintMessage hello_world; > + > + if ( ModifyThenPrintContext_alloc_context( &ctx, stdout, MODIFY_THEN_PRINT_REGEX ) < 0 ) { > + ret = -1; > + goto EXIT_WITHOUT_CLEANUP; > + } > + > + hello_world.replace_this = "Hi|Hullo"; > + hello_world.with_this = "Hello"; > + > + hello_world.str = "Hi, world!\n"; > + if ( ModifyThenPrintContext_print( ctx, &hello_world ) < 0 ) { > + ret = -1; > + goto FINISH; > + } > + > + hello_world.str = "Hullo, world!\n"; > + if ( ModifyThenPrintContext_print( ctx, &hello_world ) < 0 ) { > + ret = -1; > + goto FINISH; > + } > + > + FINISH: > + if ( ModifyThenPrintContext_free( ctx ) ) { > + ret = -1; > + goto EXIT_WITHOUT_CLEANUP; > + } > + > + EXIT_WITHOUT_CLEANUP: > + return ret; > + > +} > +``` > + > +In the example above, the `ModifyThenPrintContext` object contains information > +that's needed for exactly the lifetime of the current job (i.e. how to modify > +and where to print). Information with a longer or shorter lifetime is moved > +to `ModifyThenPrintDialect` and `ModifyThenPrintMessage`. I still find this overly complex, I would rather use a typical example of AVCodecContext for encoding or decoding or something even simpler (for example md5.h). About the internal "private" context, this is mostly relevant for FFmpeg development, and not really useful for API users (basically they don't even need to know about the private data). For example all they need to know is that for AVCodecContext generic options they can set the fields in the context itself, or use AVOptions, but they can only use AVOptions for "private" options. We are not still enforcing the use of AVOption to set all options, although we might want in the future. > + > +FFmpeg uses the context pattern to solve a variety of problems. But the most > +common contexts (AVCodecContext, AVFormatContext etc.) tend to have a lot of > +requirements in common: > + > +- need to query, set and get options > + - including options whose implementation is not part of the public API > +- need to configure log message verbosity and content > + > +FFmpeg gradually converged on the AVClass struct to store that information, > +then converged on the @ref avoptions "AVOptions" system to manipulate it. > +So the terms "context", "AVClass context structure" and "AVOptions-enabled > +struct" are often used interchangeably when it's not important to emphasise > +the difference. But for example, AVMediaCodecContext uses the context > +pattern, but is not an AVClass context structure, so cannot be manipulated > +with AVOptions. > + > +To understand AVClass context structures, consider the `libx264` encoder: > + > +- it has to support common encoder options like "bitrate" > +- it has to support encoder-specific options like "profile" > + - the exact options could change quickly if a legal ruling forces a change of backend > +- it has to provide useful feedback about unsupported options > + > +Common encoder options like "bitrate" are stored in the AVCodecContext class, > +while encoder-specific options like "profile" are stored in an X264Context > +instance in AVCodecContext::priv_data. These options are then exposed through > +a tree of AVOption objects, which include user-visible help text and > +machine-readable information about the memory location to read/write > +each option. Common @ref avoptions "AVOptions" functionality lets end users > +get and set those values, and provides readable feedback about errors. But > +even though they can be manipulated through an API, the X264Context class is > +private and new releases can modify it without affecting the public interface. > + I like this section, looks useful to explain the internals. > +FFmpeg itself uses the context design pattern to solve many problems. > +You can use this pattern anywhere it would be useful, and may want to use > +AVClass and @ref avoptions "AVOptions" if they're relevant to your situation. But again, I'm confused by this since it's confusing two levels: internal API development and API usage. When you write "may want to use" it seems to refer to the former, but the user should not really care about this (unless he wants to know how the internal implementation works). In fact, while one user might want to use the FFmpeg API as a generic development toolkit (and therefore create its own custom API with AVClass and AVOptions) I don't think this is really very common. _______________________________________________ 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".