[FFmpeg-devel] [PATCH 4/6] doc/developer: add a code behaviour section to development policy

[Stefano Sabatini]

Il sab 26 ago 2023, 20:08 Anton Khirnov <anton at khirnov.net> ha scritto:

> Document our longstanding de facto policies on things like correctness,
> thread-safety, UB, etc.
>

UB?

---
>  doc/developer.texi | 50 +++++++++++++++++++++++++++++++++-------------
>  1 file changed, 36 insertions(+), 14 deletions(-)
>
> diff --git a/doc/developer.texi b/doc/developer.texi
> index df43119f98..afa0148137 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -274,10 +274,6 @@ symbols. If in doubt, just avoid names starting with
> @code{_} altogether.
>  @section Miscellaneous conventions
>
>  @itemize @bullet
> - at item
> -fprintf and printf are forbidden in libavformat and libavcodec,
> -please use av_log() instead.
> -
>  @item
>  Casts should be used only when necessary. Unneeded parentheses
>  should also be avoided if they don't make the code easier to understand.
> @@ -286,6 +282,42 @@ should also be avoided if they don't make the code
> easier to understand.
>  @anchor{Development Policy}
>  @chapter Development Policy
>
> + at section Code behaviour
> +
> + at subheading Correctness
> +The code must be valid. It must not crash, abort, access invalid
> pointers, leak
> +memory, cause data races or signed integer overflow, or otherwise invoke
> +undefined behaviour.


Invoke => assume?

Error codes should be checked and, when applicable,
> +forwarded to the caller.
> +
> + at subheading Thread- and library-safety
> +Our libraries may be called by multiple independent callers in the same
> process.
> +These calls may happen from any number of threads and the different call
> sites
> +may not be aware of each other - e.g. a user program may be calling us
> directly,
>

Calling us -> calling the/our libraries

+and use one or more libraries that also call us. The code must behave
> correctly
> +under such conditions.
> +
> + at subheading Robustness
> +The code must treat as untrusted any bytestream received from a caller or
> read
> +from a file, network, etc. It must not misbehave when arbitrary data is
> sent to
> +it - typically it should print an error message and return
> + at code{AVERROR_INVALIDDATA} on encountering invalid input data.
> +
> + at subheading Memory allocation
> +The code must use the @code{av_malloc()} family of functions from
> + at file{libavutil/mem.h} to perform all memory allocation, except in
> special cases
> +(e.g. when interacting with an external library that requires a specific
> +allocator to be used).
> +
> +All allocations should be checked and @code{AVERROR(ENOMEM)} returned on
> +failure. A common mistake is that error paths leak memory - make sure
> that does
> +not happen.
> +
> + at subheading stdio
> +Our libraries must not access the stdio streams stdin/stdout/stderr
> directly
> +(e.g. via @code{printf()} family of functions), as that is not
> library-safe. For
> +logging, use @code{av_log()}.


Lgtm otherwise, thanks.

>
>