[libcamera-devel] [PATCH 1/4] Documentation: coding_style: Add object ownership rules

[Niklas Söderlund]

Hi Laurent,

Thanks for your work.

On 2019-01-18 01:59:13 +0200, Laurent Pinchart wrote:
> Object ownership is a complex topic that can lead to many issues, from
> memory leak to crashes. Document the rules that libcamera enforces to
> make object ownership tracking explicit.
> 
> This is a first version of the rules and is expected to be expanded as
> the library is developed.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

I think this is a really good starting point to document this complex 
topic.

Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>

> ---
>  Documentation/coding-style.rst | 62 ++++++++++++++++++++++++++++++++++
>  1 file changed, 62 insertions(+)
> 
> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> index f8d2fdfeda8e..f77325239bfa 100644
> --- a/Documentation/coding-style.rst
> +++ b/Documentation/coding-style.rst
> @@ -81,6 +81,68 @@ C++-11-specific features:
>    overused.
>  * Variadic class and function templates
>  
> +Object Ownership
> +~~~~~~~~~~~~~~~~
> +
> +libcamera creates and destroys many objects at runtime, for both objects
> +internal to the library and objects exposed to the user. To guarantee proper
> +operation without use after free, double free or memory leaks, knowing who owns
> +each object at any time is crucial. The project has enacted a set of rules to
> +make object ownership tracking as explicit and fool-proof as possible.
> +
> +In the context of this section, the terms object and instance are used
> +interchangeably and both refer to an instance of a class. The term reference
> +refers to both C++ references and C++ pointers in their capacity to refer to an
> +object. Passing a reference means offering a way to a callee to obtain a
> +reference to an object that the caller has a valid reference to. Borrowing a
> +reference means using a reference passed by a caller without ownership transfer
> +based on the assumption that the caller guarantees the validate of the
> +reference for the duration of the operation that borrows the reference.
> +
> +#. Single Owner Objects
> +
> +   * By default an object has a single owner at any time.
> +   * References to a single owner object can be borrowed by passing them from
> +     the owner to the borrower, providing that
> +
> +     * the owner guarantees the validity of the reference for the whole duration
> +       of borrowing, and
> +     * the borrower doesn't access the reference after the end of the borrowing.
> +
> +     When borrowing from caller to callee for the duration of a function call,
> +     this implies that the callee shall not keep any stored reference after it
> +     returns. These rules applies to the callee and all the functions it calls,
> +     directly or indirectly.
> +   * When the object doesn't need to be modified and may not be null, borrowed
> +     references are passed as 'const &'.
> +   * When the object may be modified or can be null, borrowed references are
> +     passed as pointers. Unless otherwise specified, pointers passed to
> +     functions are considered as borrowed references valid for the duration of
> +     the function only.
> +   * Single ownership is emphasized as much as possible by storing the unique
> +     reference as a std::unique_ptr<>.
> +   * Ownership is transfered by passing the reference as a std::unique_ptr<>.
> +
> +#. Shared Objects
> +
> +   * Objects that may have multiple owners at a given time are called shared
> +     objects. They are reference-counted and live as long as any references to
> +     the object exist.
> +   * Shared objects are created with std::make_shared<> or
> +     std::allocate_shared<> an stored in an std::shared_ptr<>.
> +   * Borrowed references to shared objects are passed with the same rules as for
> +     single owner objects.
> +   * Ownership is shared by creating and passing copies of any valid
> +     std::shared_ptr<> reference. Ownership is released by destroying the
> +     corresponding std::shared_ptr<>.
> +
> +.. attention:: Long term borrowing of single owner objects is allowed. Example
> +   use cases are implementation of the singleton pattern (where the singleton
> +   guarantees the validity of the reference forever), or returning references
> +   to global objects whose lifetime matches the lifetime of the application. As
> +   long term borrowing isn't marked through language constructs, it shall be
> +   documented explicitly in details in the API.
> +
>  
>  Tools
>  -----
> -- 
> Regards,
> 
> Laurent Pinchart
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel at lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

-- 
Regards,
Niklas Söderlund