Base class to manage private data through a d-pointer. More...
Classes | |
| class | Private |
| Base class for private data managed through a d-pointer. More... | |
Public Member Functions | |
| Extensible (std::unique_ptr< Private > d) | |
| Construct an instance of an Extensible class. More... | |
Protected Member Functions | |
| template<typename T > | |
| const T * | _d () const |
| Retrieve the private data instance. More... | |
| template<typename T > | |
| T * | _d () |
| Retrieve the private data instance. More... | |
Detailed Description
Base class to manage private data through a d-pointer.
The Extensible class provides a base class to implement the d-pointer design pattern (also known as opaque pointer or pImpl idiom). It helps creating public classes that can be extended without breaking their ABI. Such classes store their private data in a separate private data object, referenced by a pointer in the public class (hence the name d-pointer).
Classes that follow this design pattern are referred herein as extensible classes. To be extensible, a class PublicClass shall:
- inherit from the Extensible class or from another extensible class
- invoke the LIBCAMERA_DECLARE_PRIVATE() macro at the very top of the class definition
- define a private data class named PublicClass::Private that inherits from the Private data class of the base class
- invoke the LIBCAMERA_DECLARE_PUBLIC() macro at the very top of the Private data class definition
- pass a pointer to a newly allocated Private data object to the constructor of the base class
Additionally, if the PublicClass is not final, it shall expose one or more constructors that takes a pointer to a Private data instance, to be used by derived classes.
The Private class is fully opaque to users of the libcamera public API. Internally, it can be kept private to the implementation of PublicClass, or be exposed to other classes. In the latter case, the members of the Private class need to be qualified with appropriate access specifiers. The PublicClass and Private classes always have full access to each other's protected and private members.
The PublicClass exposes its Private data pointer through the _d() function. In the other direction, the pointer to the PublicClass can be retrieved in functions of the Private class using the LIBCAMERA_O_PTR() macro.
Constructor & Destructor Documentation
◆ Extensible()
| libcamera::Extensible::Extensible | ( | std::unique_ptr< Private > | d | ) |
Construct an instance of an Extensible class.
- Parameters
-
[in] d Pointer to the private data instance
The private data lifetime is managed by the Extensible class, which destroys it when the Extensible instance is destroyed.
Member Function Documentation
◆ _d() [1/2]
|
inlineprotected |
Retrieve the private data instance.
This template function isn't meant to be called directly. Instead, classes derived from Extensible get, through the LIBCAMERA_DECLARE_PRIVATE() macro, overriden _d() functions that return the correct pointer type to the corresponding derived Private class.
The lifetime of the private data is tied to the Extensible class. The caller shall not retain any reference to the returned pointer for longer than it holds a reference to the Extensible instance.
- Returns
- A pointer to the private data instance
◆ _d() [2/2]
|
inlineprotected |
Retrieve the private data instance.
This template function isn't meant to be called directly. Instead, classes derived from Extensible get, through the LIBCAMERA_DECLARE_PRIVATE() macro, overriden _d() functions that return the correct pointer type to the corresponding derived Private class.
The lifetime of the private data is tied to the Extensible class. The caller shall not retain any reference to the returned pointer for longer than it holds a reference to the Extensible instance.
- Returns
- A pointer to the private data instance
The documentation for this class was generated from the following files:
- include/libcamera/base/class.h
- src/libcamera/base/class.cpp
