From patchwork Tue Oct 20 01:40:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 10108 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 9F32ABDB1F for ; Tue, 20 Oct 2020 01:41:00 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 68A1861394; Tue, 20 Oct 2020 03:41:00 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="ivY+SFIO"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id E4FE660CE6 for ; Tue, 20 Oct 2020 03:40:56 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 8633E52 for ; Tue, 20 Oct 2020 03:40:56 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1603158056; bh=HJn3opyIsMo9C4szyNA7FaeB56wPdvisJKO6yY0yO98=; h=From:To:Subject:Date:In-Reply-To:References:From; b=ivY+SFIOinbX0W8LViQMGuctgBGP+I97QPMcEKG+8uZkQqlZrktwCpUEkOmjZttas 2RvqeLQZ1eXPIuB2XfrUOSYcpWR8tEJjC1ZWmenieaSspv5whkeb8DIR6ZH4M2CpfO k6uGJ4uq3dmPV3yfkjIamHqpbuYMKGpRp0kLhS8g= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Tue, 20 Oct 2020 04:40:02 +0300 Message-Id: <20201020014005.12783-3-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20201020014005.12783-1-laurent.pinchart@ideasonboard.com> References: <20201020014005.12783-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 2/5] libcamera: Add a base class to implement the d-pointer design pattern X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" 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 Reviewed-by: Niklas Söderlund Reviewed-by: Jacopo Mondi --- Changes since v1: - Don't hide variable declarations in LIBCAMERA_[DO]_PTR macros - Extend documentation - Fix typos --- include/libcamera/extensible.h | 86 +++++++++++++++++++++ include/libcamera/meson.build | 1 + src/libcamera/extensible.cpp | 134 +++++++++++++++++++++++++++++++++ src/libcamera/meson.build | 1 + 4 files changed, 222 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..ea8808ad3e3c --- /dev/null +++ b/include/libcamera/extensible.h @@ -0,0 +1,86 @@ +/* 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 + +namespace libcamera { + +#ifndef __DOXYGEN__ +#define LIBCAMERA_DECLARE_PRIVATE(klass) \ +public: \ + class Private; \ + friend class Private; + +#define LIBCAMERA_DECLARE_PUBLIC(klass) \ + friend class klass; + +#define LIBCAMERA_D_PTR(klass) \ + _d(); + +#define LIBCAMERA_O_PTR(klass) \ + _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(); + +#ifndef __DOXYGEN__ + template + const T *_o() const + { + return static_cast(o_); + } + + template + T *_o() + { + return static_cast(o_); + } +#endif + + private: + Extensible * const o_; + }; + + Extensible(Private *d); + +protected: +#ifndef __DOXYGEN__ + template + const T *_d() const + { + return static_cast(d_.get()); + } + + template + T *_d() + { + return static_cast(d_.get()); + } +#endif + +private: + const std::unique_ptr d_; +}; + +} /* namespace libcamera */ + +#endif /* __LIBCAMERA_EXTENSIBLE_H__ */ diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build index 83bc46729314..15e6b43c9585 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', 'flags.h', 'framebuffer_allocator.h', diff --git a/src/libcamera/extensible.cpp b/src/libcamera/extensible.cpp new file mode 100644 index 000000000000..1dcb0bf1b12f --- /dev/null +++ b/src/libcamera/extensible.cpp @@ -0,0 +1,134 @@ +/* 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 + +/** + * \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 points 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 + * 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. + */ + +/** + * \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 47ddb4014a61..b9f6457433f9 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -17,6 +17,7 @@ libcamera_sources = files([ 'event_dispatcher.cpp', 'event_dispatcher_poll.cpp', 'event_notifier.cpp', + 'extensible.cpp', 'file.cpp', 'file_descriptor.cpp', 'flags.cpp',