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

[Anton Khirnov]

Quoting Andreas Rheinhardt (2023-08-26 20:36:25)
> Anton Khirnov:
> > Document our longstanding de facto policies on things like correctness,
> > thread-safety, UB, etc.
> > ---
> >  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. 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,
> > +and use one or more libraries that also call us. The code must behave correctly
> > +under such conditions.
> 
> Some of this can no longer be guaranteed when FFmpeg is built without
> threading support, but called from multiple threads concurrently. Should
> this be mentioned or would it just confuse readers? (I'm leaning to the
> latter.)

I tend to agree, it's a very obscure use case anyway.

But we should probably document more explicitly somewhere (and warn in
configure) what building without threads actually implies.

-- 
Anton Khirnov