[{"id":21475,"web_url":"https://patchwork.libcamera.org/comment/21475/","msgid":"","date":"2021-11-30T23:30:12","subject":"Re: [libcamera-devel] [PATCH v3 05/12] libcamera: base: Add mutex\n\tclasses with thread safety annotations","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Hiro,\n\nThank you for the patch.\n\nOn Wed, Dec 01, 2021 at 12:55:53AM +0900, Hirokazu Honda wrote:\n> This replaces Mutex and MutexLocker with our own defined classes.\n> The classes are annotated by clang thread safety annotations.\n> So we can add annotation to code where the classes are used.\n> \n> v4l2 code needs to be annotated, which violates Mutex capability.\n> \n> Signed-off-by: Hirokazu Honda \n> ---\n> include/libcamera/base/meson.build | 1 +\n> include/libcamera/base/mutex.h | 131 +++++++++++++++++++++++++++++\n> include/libcamera/base/thread.h | 7 +-\n> src/libcamera/base/meson.build | 1 +\n> src/libcamera/base/mutex.cpp | 121 ++++++++++++++++++++++++++\n> src/libcamera/base/thread.cpp | 15 ----\n> src/v4l2/v4l2_camera_proxy.h | 5 +-\n> 7 files changed, 258 insertions(+), 23 deletions(-)\n> create mode 100644 include/libcamera/base/mutex.h\n> create mode 100644 src/libcamera/base/mutex.cpp\n> \n> diff --git a/include/libcamera/base/meson.build b/include/libcamera/base/meson.build\n> index 1a71ce5a..37c4435a 100644\n> --- a/include/libcamera/base/meson.build\n> +++ b/include/libcamera/base/meson.build\n> @@ -13,6 +13,7 @@ libcamera_base_headers = files([\n> 'flags.h',\n> 'log.h',\n> 'message.h',\n> + 'mutex.h',\n> 'object.h',\n> 'private.h',\n> 'semaphore.h',\n> diff --git a/include/libcamera/base/mutex.h b/include/libcamera/base/mutex.h\n> new file mode 100644\n> index 00000000..2792551c\n> --- /dev/null\n> +++ b/include/libcamera/base/mutex.h\n> @@ -0,0 +1,131 @@\n> +/* SPDX-License-Identifier: LGPL-2.1-or-later */\n> +/*\n> + * Copyright (C) 2021, Google Inc.\n> + *\n> + * thread.h - Thread support\n\nCopy and paste ? :-)\n\n> + */\n> +\n> +#pragma once\n> +\n> +#include \n> +#include \n> +\n> +#include \n> +\n> +namespace libcamera {\n> +\n> +class ConditionVariable;\n> +\n> +#ifndef __DOXYGEN__\n> +class LIBCAMERA_TSA_SCOPED_CAPABILITY MutexLocker;\n> +#else\n> +class MutexLocker;\n> +#endif /* __DOXYGEN__ */\n\nYou can drop this forward declaration if you used \"friend class\nMutexLocker\" below. Same for ConditionVariable.\n\n> +\n> +/* \\todo using Mutex = std::mutex if lib++ is used. */\n> +\n> +#ifndef __DOXYGEN__\n> +class LIBCAMERA_TSA_CAPABILITY(\"mutex\") Mutex final\n> +#else\n> +class Mutex final\n> +#endif /* __DOXYGEN__ */\n\nThe conditional compilation could be removed there if we added\n\ndiff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in\nindex 3d20e3ca460f..aaa09ecb1db7 100644\n--- a/Documentation/Doxyfile.in\n+++ b/Documentation/Doxyfile.in\n@@ -2041,7 +2041,8 @@ INCLUDE_FILE_PATTERNS = *.h\n\n PREDEFINED = __DOXYGEN__ \\\n __cplusplus \\\n- __attribute__(x)=\n+ __attribute__(x)= \\\n+\t\t\t LIBCAMERA_TSA_CAPABILITY(x)=\n\n # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this\n # tag can be used to specify a list of macro names that should be expanded. The\n\nI'm not sure if that's better though. It would be nicer to specify\n\nEXPAND_AS_DEFINED = LIBCAMERA_TSA_*\n\n(or a similar syntax), but that's not supported by Doxygen :-( It\nshouldn't be hard to implement, but I don't know if it would be accepted\nupstream.\n\nI've also tried setting EXPAND_ONLY_PREDEF to NO, and it didn't help. I\nmay be missing something there.\n\n> +{\n> +public:\n> +\tconstexpr Mutex()\n> +\t{\n> +\t}\n> +\n> +\tvoid lock() LIBCAMERA_TSA_ACQUIRE()\n> +\t{\n> +\t\tmutex_.lock();\n> +\t}\n> +\n> +\tvoid unlock() LIBCAMERA_TSA_RELEASE()\n> +\t{\n> +\t\tmutex_.unlock();\n> +\t}\n> +\n> +private:\n> +\tfriend MutexLocker;\n> +\n> +\tstd::mutex mutex_;\n> +};\n> +\n> +#ifndef __DOXYGEN__\n> +class LIBCAMERA_TSA_SCOPED_CAPABILITY MutexLocker final\n> +#else\n> +class MutexLocker final\n> +#endif /* __DOXYGEN__ */\n> +{\n> +public:\n> +\texplicit MutexLocker(Mutex &mutex) LIBCAMERA_TSA_ACQUIRE(mutex)\n> +\t\t: lock_(mutex.mutex_)\n> +\t{\n> +\t}\n> +\n> +\tMutexLocker(Mutex &mutex, std::defer_lock_t t) noexcept LIBCAMERA_TSA_EXCLUDES(mutex)\n> +\t\t: lock_(mutex.mutex_, t)\n> +\t{\n> +\t}\n> +\n> +\t~MutexLocker() LIBCAMERA_TSA_RELEASE()\n> +\t{\n> +\t}\n> +\n> +\tvoid lock() LIBCAMERA_TSA_ACQUIRE()\n> +\t{\n> +\t\tlock_.lock();\n> +\t}\n> +\n> +\tbool try_lock() LIBCAMERA_TSA_TRY_ACQUIRE(true)\n> +\t{\n> +\t\treturn lock_.try_lock();\n> +\t}\n> +\n> +\tvoid unlock() LIBCAMERA_TSA_RELEASE()\n> +\t{\n> +\t\tlock_.unlock();\n> +\t}\n> +\n> +private:\n> +\tfriend ConditionVariable;\n> +\n> +\tstd::unique_lock lock_;\n> +};\n> +\n> +class ConditionVariable final\n> +{\n> +public:\n> +\tConditionVariable()\n> +\t{\n> +\t}\n> +\n> +\tvoid notify_one() noexcept\n> +\t{\n> +\t\tcv_.notify_one();\n> +\t}\n> +\n> +\tvoid notify_all() noexcept\n> +\t{\n> +\t\tcv_.notify_all();\n> +\t}\n> +\n> +\ttemplate\n> +\tvoid wait(MutexLocker &locker, Predicate stopWaiting)\n> +\t{\n> +\t\tcv_.wait(locker.lock_, stopWaiting);\n> +\t}\n> +\n> +\ttemplate\n> +\tbool wait_for(MutexLocker &locker,\n> +\t\t const std::chrono::duration &relTime,\n> +\t\t Predicate stopWaiting)\n> +\t{\n> +\t\treturn cv_.wait_for(locker.lock_, relTime, stopWaiting);\n> +\t}\n> +\n> +private:\n> +\tstd::condition_variable cv_;\n> +};\n> +\n> +} /* namespace libcamera */\n> diff --git a/include/libcamera/base/thread.h b/include/libcamera/base/thread.h\n> index 1ebf8363..44678c34 100644\n> --- a/include/libcamera/base/thread.h\n> +++ b/include/libcamera/base/thread.h\n> @@ -7,15 +7,14 @@\n> \n> #pragma once\n> \n> -#include \n> #include \n> -#include \n> #include \n> #include \n> \n> #include \n> \n> #include \n> +#include \n> #include \n> #include \n> \n> @@ -27,10 +26,6 @@ class Object;\n> class ThreadData;\n> class ThreadMain;\n> \n> -using ConditionVariable = std::condition_variable;\n> -using Mutex = std::mutex;\n> -using MutexLocker = std::unique_lock;\n> -\n> class Thread\n> {\n> public:\n> diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build\n> index 05fed7ac..b93b8505 100644\n> --- a/src/libcamera/base/meson.build\n> +++ b/src/libcamera/base/meson.build\n> @@ -11,6 +11,7 @@ libcamera_base_sources = files([\n> 'flags.cpp',\n> 'log.cpp',\n> 'message.cpp',\n> + 'mutex.cpp',\n> 'object.cpp',\n> 'semaphore.cpp',\n> 'signal.cpp',\n> diff --git a/src/libcamera/base/mutex.cpp b/src/libcamera/base/mutex.cpp\n> new file mode 100644\n> index 00000000..327b90c0\n> --- /dev/null\n> +++ b/src/libcamera/base/mutex.cpp\n> @@ -0,0 +1,121 @@\n> +/* SPDX-License-Identifier: LGPL-2.1-or-later */\n> +/*\n> + * Copyright (C) 2021, Google Inc.\n> + *\n> + * mutex.cpp - Mutex classes with clang thread safety annotation\n> + */\n> +\n> +#include \n> +\n> +/**\n> + * \\file base/mutex.h\n> + * \\brief Mutex classes with clang thread safety annotation\n> + */\n> +\n> +namespace libcamera {\n> +\n> +/**\n> + * \\class Mutex\n> + * \\brief std::mutex wrapper with clang thread safety annotation\n> + */\n\nLet's expand this a little bit.\n\n/**\n * \\class Mutex\n * \\brief std::mutex wrapper with clang thread safety annotation\n *\n * The Mutex class wraps a std::mutex instance to add clang thread safety\n * annotation support. The class exposes the same interface as std::mutex and\n * can be used as a transparent replacement. It integrates with the\n * MutexLocker and ConditionVariable classes.\n *\n * See https://en.cppreference.com/w/cpp/thread/mutex for the complete API\n * documentation.\n */\n\nSame below.\n\n> +\n> +/**\n> + * \\fn Mutex::Mutex()\n> + * \\brief Construct a Mutex instance\n> + */\n\nI wonder, should we drop the documentation for individual members ?\nOtherwise we'll end up replicating the C++ library documentation. To\navoid doxygen warnings, we could have, in the .h file,\n\n#ifndef __DOXYGEN__\n\nclass LIBCAMERA_TSA_CAPABILITY(\"mutex\") Mutex final\n{\npublic:\n\t...\n};\n\nclass LIBCAMERA_TSA_SCOPED_CAPABILITY MutexLocker\n{\npublic:\n\t...\n};\n\nclass ConditionVariable final\n{\npublic:\n\t...\n};\n\n#else\n\nclass Mutex final\n{\n};\n\nclass MutexLocker final\n{\n};\n\nclass ConditionVariable final\n{\n};\n\n#endif /* __DOXYGEN__ */\n\n> +\n> +/**\n> + * \\fn Mutex::lock()\n> + * \\brief Locks std::mutex\n> + */\n> +\n> +/**\n> + * \\fn Mutex::unlock()\n> + * \\brief Unlocks std::mutex\n> + */\n> +\n> +/**\n> + * \\class MutexLocker\n> + * \\brief std::unique_lock wrapper with clang thread safety annotation\n> + */\n> +\n> +/**\n> + * \\fn MutexLocker::MutexLocker(Mutex &mutex)\n> + * \\brief Constructs MutexLocker with \\a mutex as as the associated mutex and\n> + * locks \\a mutex\n> + * \\param[in] mutex Mutex to be locked/unlocked by MutexLocker\n> + *\n> + * This blocks until \\a mutex is acquired.\n> + */\n> +\n> +/**\n> + * \\fn MutexLocker::MutexLocker(Mutex &mutex, std::defer_lock_t t)\n> + * \\brief Constructs MutexLocker with \\a mutex as as the associated mutex but\n> + * does not lock \\a mutex\n> + * \\param[in] mutex Mutex to be locked/unlocked by MutexLocker\n> + * \\param[in] t mark to specify this constructor is called1\n> + *\n> + */\n> +\n> +/**\n> + * \\fn MutexLocker::~MutexLocker()\n> + * \\brief Destroys MutexLocker and unlock the associated mutex if it is locked\n> + */\n> +\n> +/**\n> + * \\fn MutexLocker::lock()\n> + * \\brief Locks the associated mutex\n> + */\n> +\n> +/**\n> + * \\fn MutexLocker::try_lock()\n> + * \\brief Tries to lock the associated mutex\n> + * \\return True if the ownership of the mutex has been acquired successfully,\n> + false otherwise.\n> + */\n> +\n> +/**\n> + * \\fn MutexLocker::unlock()\n> + * \\brief Unlocks the associated mutex\n> + */\n> +\n> +/**\n> + * \\class ConditionVariable\n> + * \\brief std::condition_variable wrapper with clang thread safety annotation\n> + */\n> +\n> +/**\n> + * \\fn ConditionVariable::ConditionVariable()\n> + * \\brief Constructs ConditionVariable\n> + */\n> +\n> +/**\n> + * \\fn ConditionVariable::notify_one()\n> + * \\brief Delegates std::condition_variable::notify_one()\n> + */\n> +\n> +/**\n> + * \\fn ConditionVariable::notify_all()\n> + * \\brief Delegates std::condition_variable::notify_all()\n> + */\n> +\n> +/**\n> + * \\fn ConditionVariable::wait(MutexLocker& locker, Predicate stopWaiting)\n> + * \\brief Call std::condition_variable::wait() with \\a locker and \\a stopWaiting\n> + * \\param[in] locker MutexLocker that is locked/unlocked during wait()\n> + * \\param[in] stopWaiting The predicate to be satisfied\n> + */\n> +\n> +/**\n> + * \\fn ConditionVariable::wait_for(MutexLocker& locker,\n> + const std::chrono::duration &relTime,\n> +\t\t\t\t Predicate stopWaiting)\n> + * \\brief Call std::condition_variable::wait_for() with \\a locker, \\a relTime,\n> + \\a stopWaiting\n> + * \\param[in] locker MutexLocker that is locked/unlocked during wait()\n> + * \\param[in] relTime std::chrono::duration representing the maximum time to\n> + spend waiting\n> + * \\param[in] stopWaiting The predicate to be satisfied\n> + */\n> +\n> +} /* namespace libcamera */\n> diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp\n> index b893135f..b2043b7e 100644\n> --- a/src/libcamera/base/thread.cpp\n> +++ b/src/libcamera/base/thread.cpp\n> @@ -204,21 +204,6 @@ ThreadData *ThreadData::current()\n> \treturn data;\n> }\n> \n> -/**\n> - * \\typedef ConditionVariable\n> - * \\brief An alias for std::condition_variable\n> - */\n> -\n> -/**\n> - * \\typedef Mutex\n> - * \\brief An alias for std::mutex\n> - */\n> -\n> -/**\n> - * \\typedef MutexLocker\n> - * \\brief An alias for std::unique_lock\n> - */\n> -\n> /**\n> * \\class Thread\n> * \\brief A thread of execution\n> diff --git a/src/v4l2/v4l2_camera_proxy.h b/src/v4l2/v4l2_camera_proxy.h\n> index 040954dd..23be995d 100644\n> --- a/src/v4l2/v4l2_camera_proxy.h\n> +++ b/src/v4l2/v4l2_camera_proxy.h\n> @@ -14,7 +14,8 @@\n> #include \n> #include \n> \n> -#include \n> +#include \n> +#include \n\nDo you think we could we drop manual inclusion of thread_annotations.h\n(here and in other patches) as it's included by mutex.h ? We try not to\nrely on indirect inclusion to avoid compilation breakages, but in this\ncase thread_annotations.h is guaranteed to be included by mutex.h (if it\nwasn't, mutex.h wouldn't exist in the first place, we would use the\nstd::* types).\n\n> \n> #include \n> \n> @@ -59,7 +60,7 @@ private:\n> \tint vidioc_querybuf(V4L2CameraFile *file, struct v4l2_buffer *arg);\n> \tint vidioc_qbuf(V4L2CameraFile *file, struct v4l2_buffer *arg);\n> \tint vidioc_dqbuf(V4L2CameraFile *file, struct v4l2_buffer *arg,\n> -\t\t\t libcamera::Mutex *lock);\n> +\t\t\t libcamera::Mutex *lock) LIBCAMERA_TSA_REQUIRES(*lock);\n> \tint vidioc_streamon(V4L2CameraFile *file, int *arg);\n> \tint vidioc_streamoff(V4L2CameraFile *file, int *arg);\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 6B3CABF415\n\tfor ;\n\tTue, 30 Nov 2021 23:30:41 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id B589460720;\n\tWed, 1 Dec 2021 00:30:40 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 63FB360592\n\tfor ;\n\tWed, 1 Dec 2021 00:30:38 +0100 (CET)","from pendragon.ideasonboard.com (62-78-145-57.bb.dnainternet.fi\n\t[62.78.145.57])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id C92E08AE;\n\tWed, 1 Dec 2021 00:30:37 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"wf0YQPaD\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1638315038;\n\tbh=hTqgji5fPbjH5c74wnvCbXekfXc232sHVEQv5rm5XhI=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=wf0YQPaDJ4WvEu6Bvp4jwM9OWYg10Bkb1bnydYJv+73NLzEYgfjE65W3cVzNVe3gM\n\tzGxgdkvrEEwcHQLbOzR/5NhqArABTh5jEbWVunfBBdRGLsByqHY2Kyd66Due3TQtyo\n\tLvzCAHF2xm2H09/CQ7DKjdfLkeH5e/uYM2r4n5Rg=","Date":"Wed, 1 Dec 2021 01:30:12 +0200","From":"Laurent Pinchart ","To":"Hirokazu Honda ","Message-ID":"","References":"<20211130155600.2203123-1-hiroh@chromium.org>\n\t<20211130155600.2203123-6-hiroh@chromium.org>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20211130155600.2203123-6-hiroh@chromium.org>","Subject":"Re: [libcamera-devel] [PATCH v3 05/12] libcamera: base: Add mutex\n\tclasses with thread safety annotations","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]