[libcamera-devel] [PATCH 1/4] libcamera: Add a base class to implement the d-pointer design pattern

[Laurent Pinchart]

The d-pointer design patterns helps creating public classes that can be
extended without breaking their ABI. To facilitate usage of the pattern
in libcamera, create a base Extensible class with associated macros.

Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
---
 include/libcamera/extensible.h |  80 +++++++++++++++++++++
 include/libcamera/meson.build  |   1 +
 src/libcamera/extensible.cpp   | 127 +++++++++++++++++++++++++++++++++
 src/libcamera/meson.build      |   1 +
 4 files changed, 209 insertions(+)
 create mode 100644 include/libcamera/extensible.h
 create mode 100644 src/libcamera/extensible.cpp

diff --git a/include/libcamera/extensible.h b/include/libcamera/extensible.h
new file mode 100644
index 000000000000..0fa3bcdbeac5
--- /dev/null
+++ b/include/libcamera/extensible.h
@@ -0,0 +1,80 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2020, Google Inc.
+ *
+ * extensible.h - Utilities to create extensible public classes with stable ABIs
+ */
+#ifndef __LIBCAMERA_EXTENSIBLE_H__
+#define __LIBCAMERA_EXTENSIBLE_H__
+
+#include <memory>
+
+namespace libcamera {
+
+#ifndef __DOXYGEN__
+#define LIBCAMERA_DECLARE_PRIVATE(klass)				\
+public:									\
+	class Private;							\
+	friend class Private;
+
+#define LIBCAMERA_DECLARE_PUBLIC(klass)					\
+private:								\
+	friend class klass;						\
+	const klass *_o() const						\
+	{								\
+		return static_cast<const klass *>(o_);			\
+	}								\
+	klass *_o()							\
+	{								\
+		return static_cast<klass *>(o_);			\
+	}
+
+#define LIBCAMERA_D_PTR(klass)						\
+	auto * const d = _d<klass::Private>();
+
+#define LIBCAMERA_O_PTR(klass)						\
+	auto * const o = _o();
+
+#else
+#define LIBCAMERA_DECLARE_PRIVATE(klass)
+#define LIBCAMERA_DECLARE_PUBLIC(klass)
+#define LIBCAMERA_D_PTR(klass)
+#define LIBCAMERA_O_PTR(klass)
+#endif
+
+class Extensible
+{
+public:
+	class Private
+	{
+	public:
+		Private(Extensible *o);
+		virtual ~Private();
+
+		Extensible * const o_;
+	};
+
+	Extensible(Private *d);
+
+protected:
+#ifndef __DOXYGEN__
+	template<typename T>
+	const T *_d() const
+	{
+		return static_cast<const T *>(d_.get());
+	}
+
+	template<typename T>
+	T *_d()
+	{
+		return static_cast<T*>(d_.get());
+	}
+#endif
+
+private:
+	const std::unique_ptr<Private> d_;
+};
+
+} /* namespace libcamera */
+
+#endif /* __LIBCAMERA_EXTENSIBLE_H__ */
diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build
index cdb8e0372e77..0a06dab0e105 100644
--- a/include/libcamera/meson.build
+++ b/include/libcamera/meson.build
@@ -8,6 +8,7 @@ libcamera_public_headers = files([
     'controls.h',
     'event_dispatcher.h',
     'event_notifier.h',
+    'extensible.h',
     'file_descriptor.h',
     'framebuffer_allocator.h',
     'geometry.h',
diff --git a/src/libcamera/extensible.cpp b/src/libcamera/extensible.cpp
new file mode 100644
index 000000000000..b2a7fc5d5304
--- /dev/null
+++ b/src/libcamera/extensible.cpp
@@ -0,0 +1,127 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2020, Google Inc.
+ *
+ * extensible.cpp - Utilities to create extensible public classes with stable ABIs
+ */
+
+#include <libcamera/extensible.h>
+
+/**
+ * \file extensible.h
+ * \brief Utilities to create extensible public classes with stable ABIs
+ */
+
+namespace libcamera {
+
+/**
+ * \def LIBCAMERA_DECLARE_PRIVATE
+ * \brief Declare private data for a public class
+ * \param klass The public class name
+ *
+ * The LIBCAMERA_DECLARE_PRIVATE() macro plumbs the infrastructure necessary to
+ * make a class manage its private data through a d-pointer. It shall be used at
+ * the very top of the class definition, with the public class name passed as
+ * the \a klass parameter.
+ */
+
+/**
+ * \def LIBCAMERA_DECLARE_PUBLIC
+ * \brief Declare public data for a private class
+ * \param klass The public class name
+ *
+ * The LIBCAMERA_DECLARE_PUBLIC() macro is the counterpart of
+ * LIBCAMERA_DECLARE_PRIVATE() to be used in the private data class. It shall be
+ * used at the very top of the private class definition, with the public class
+ * name passed as the \a klass parameter.
+ */
+
+/**
+ * \def LIBCAMERA_D_PTR(klass)
+ * \brief Retrieve the private data pointer
+ * \param[in] klass The public class name
+ *
+ * This macro can be used in any member function of a class that inherits,
+ * directly or indirectly, from the Extensible class, to create a local
+ * variable named 'd' that points to the class' private data instance.
+ */
+
+/**
+ * \def LIBCAMERA_O_PTR(klass)
+ * \brief Retrieve the public instance corresponding to the private data
+ * \param[in] klass The public class name
+ *
+ * This macro is the counterpart of LIBCAMERA_D_PTR() for private data classes.
+ * It can be used in any member function of the private data class to create a
+ * local variable named 'o' that ponits to the public class instance
+ * corresponding to the private data.
+ */
+
+/**
+ * \class Extensible
+ * \brief Base class to manage private data through a d-pointer
+ *
+ * The Extensible class provides a base class to implement the
+ * <a href="https://wiki.qt.io/D-Pointer">d-pointer</a> design pattern (also
+ * known as <a href="https://en.wikipedia.org/wiki/Opaque_pointer">opaque pointer</a>
+ * or <a href="https://en.cppreference.com/w/cpp/language/pimpl">pImpl idiom</a>).
+ * 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 std::unique_ptr 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.
+ */
+
+/**
+ * \brief Construct an instance of an Extensible class
+ * \param[in] d Pointer to the private data instance
+ */
+Extensible::Extensible(Extensible::Private *d)
+	: d_(d)
+{
+}
+
+/**
+ * \var Extensible::d_
+ * \brief Pointer to the private data instance
+ */
+
+/**
+ * \class Extensible::Private
+ * \brief Base class for private data managed through a d-pointer
+ */
+
+/**
+ * \brief Construct an instance of an Extensible class private data
+ * \param[in] o Pointer to the public class object
+ */
+Extensible::Private::Private(Extensible *o)
+	: o_(o)
+{
+}
+
+Extensible::Private::~Private()
+{
+}
+
+/**
+ * \var Extensible::Private::o_
+ * \brief Pointer to the public class object
+ */
+
+} /* namespace libcamera */
diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
index 0e6ecf5060a4..16c9c81440f5 100644
--- a/src/libcamera/meson.build
+++ b/src/libcamera/meson.build
@@ -16,6 +16,7 @@ libcamera_sources = files([
     'event_dispatcher.cpp',
     'event_dispatcher_poll.cpp',
     'event_notifier.cpp',
+    'extensible.cpp',
     'file.cpp',
     'file_descriptor.cpp',
     'formats.cpp',
-- 
Regards,

Laurent Pinchart