[{"id":30802,"web_url":"https://patchwork.libcamera.org/comment/30802/","msgid":"<20240814005735.GK5833@pendragon.ideasonboard.com>","date":"2024-08-14T00:57:35","subject":"Re: [PATCH v7 1/5] Documentation: Add Thread safety page","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Dan,\n\nThank you for the patch.\n\nOn Thu, Aug 08, 2024 at 03:09:44PM +0100, Daniel Scally wrote:\n> Move the section of the Thread support page dealing with thread safety\n> to a dedicated .dox file at Documentation/. This is done to support the\n> splitting of the Documentation into a public and internal version. With\n> a separate page, references can be made to thread safety without having\n> to include the Thread class in the doxygen run. Some sections of the new\n> page are still specific to internal implementations and so are hidden\n> with the \\internal flag and an internal section which is conditionally\n> included. For now, hardcode it to be included in the Doxyfile.\n> \n> Signed-off-by: Daniel Scally \n> ---\n> Changes since v6:\n> \n> Conditionally included any reference to thread-bound behind either the \\internal\n> directive or and internal section.\n> \n> Changes since v5:\n> \n> - Much of the content that dealt with internal implementation was moved\n> back to its place against the Thread class. The thread safety section\n> is retained in a separate page, with a single reference to the main\n> thread support page who's display is conditional on the doxygen\n> INTERNAL_DOCS directive.\n> \n> Given the scope of the changes, I dropped the R-b tags the patch had\n> accumulated\n> \n> Changes since v1:\n> \n> - New patch\n> \n> Documentation/Doxyfile.in | 5 +++-\n> Documentation/thread-safety.dox | 48 +++++++++++++++++++++++++++++++++\n> src/libcamera/base/thread.cpp | 36 -------------------------\n> 3 files changed, 52 insertions(+), 37 deletions(-)\n> create mode 100644 Documentation/thread-safety.dox\n> \n> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in\n> index 62e63968..203f8e67 100644\n> --- a/Documentation/Doxyfile.in\n> +++ b/Documentation/Doxyfile.in\n> @@ -17,13 +17,15 @@ EXTENSION_MAPPING = h=C++\n> \n> TOC_INCLUDE_HEADINGS = 0\n> \n> +ENABLED_SECTIONS = internal\n> INTERNAL_DOCS = YES\n> CASE_SENSE_NAMES = YES\n> \n> QUIET = YES\n> WARN_AS_ERROR = @WARN_AS_ERROR@\n> \n> -INPUT = \"@TOP_SRCDIR@/include/libcamera\" \\\n> +INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n> + \"@TOP_SRCDIR@/include/libcamera\" \\\n> \"@TOP_SRCDIR@/src/ipa/ipu3\" \\\n> \"@TOP_SRCDIR@/src/ipa/libipa\" \\\n> \"@TOP_SRCDIR@/src/libcamera\" \\\n> @@ -32,6 +34,7 @@ INPUT = \"@TOP_SRCDIR@/include/libcamera\" \\\n> \n> FILE_PATTERNS = *.c \\\n> *.cpp \\\n> + *.dox \\\n> *.h\n> \n> RECURSIVE = YES\n> diff --git a/Documentation/thread-safety.dox b/Documentation/thread-safety.dox\n> new file mode 100644\n> index 00000000..1a610035\n> --- /dev/null\n> +++ b/Documentation/thread-safety.dox\n> @@ -0,0 +1,48 @@\n> +/**\n> + * \\page thread-safety Reentrancy and Thread-Safety\n> + *\n> + * Through the documentation, several terms are used to define how classes and\n> + * their member functions can be used from multiple threads.\n> + *\n> + * - A **reentrant** function may be called simultaneously from multiple\n> + * threads if and only if each invocation uses a different instance of the\n> + * class. This is the default for all member functions not explictly marked\n> + * otherwise.\n> + *\n> + * - \\anchor thread-safe A **thread-safe** function may be called\n> + * simultaneously from multiple threads on the same instance of a class. A\n> + * thread-safe function is thus reentrant. Thread-safe functions may also be\n> + * called simultaneously with any other reentrant function of the same class\n> + * on the same instance.\n> + *\n> + * \\internal\n> + * - \\anchor thread-bound A **thread-bound** function may be called only from\n> + * the thread that the class instances lives in (see section \\ref\n> + * thread-objects). For instances of classes that do not derive from the\n> + * Object class, this is the thread in which the instance was created. A\n> + * thread-bound function is not thread-safe, and may or may not be reentrant.\n> + * \\endinternal\n> + *\n> + * Neither reentrancy nor thread-safety, in this context, mean that a function\n> + * may be called simultaneously from the same thread, for instance from a\n> + * callback invoked by the function. This may deadlock and isn't allowed unless\n> + * separately documented.\n> + *\n> + * \\if internal\n> + * A class is defined as reentrant, thread-safe or thread-bound if all its\n> + * member functions are reentrant, thread-safe or thread-bound respectively.\n> + * Some member functions may additionally be documented as having additional\n> + * thread-related attributes.\n> + *\n> + * \\else\n> + *\n> + * A class is defined as reentrant or thread-safe if all its member functions\n> + * are reentrant or thread-safe respectively. Some member functions may\n> + * additionally be documented as having additional thread-related attributes.\n> + *\n> + * \\endif\n\nAs the second sentence is common, I think you can share it:\n\n * \\if internal\n * A class is defined as reentrant, thread-safe or thread-bound if all its\n * member functions are reentrant, thread-safe or thread-bound respectively.\n * \\else\n * A class is defined as reentrant or thread-safe if all its member functions\n * are reentrant or thread-safe respectively.\n * \\endif\n * Some member functions may additionally be documented as having additional\n * thread-related attributes.\n\nReviewed-by: Laurent Pinchart \n\n> + *\n> + * Most classes are reentrant but not thread-safe, as making them fully\n> + * thread-safe would incur locking costs considered prohibitive for the\n> + * expected use cases.\n> + */\n> diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp\n> index 72733431..8735670b 100644\n> --- a/src/libcamera/base/thread.cpp\n> +++ b/src/libcamera/base/thread.cpp\n> @@ -64,42 +64,6 @@\n> * receiver's event loop, running in the receiver's thread. This mechanism can\n> * be overridden by selecting a different connection type when calling\n> * Signal::connect().\n> - *\n> - * \\section thread-reentrancy Reentrancy and Thread-Safety\n> - *\n> - * Through the documentation, several terms are used to define how classes and\n> - * their member functions can be used from multiple threads.\n> - *\n> - * - A **reentrant** function may be called simultaneously from multiple\n> - * threads if and only if each invocation uses a different instance of the\n> - * class. This is the default for all member functions not explictly marked\n> - * otherwise.\n> - *\n> - * - \\anchor thread-safe A **thread-safe** function may be called\n> - * simultaneously from multiple threads on the same instance of a class. A\n> - * thread-safe function is thus reentrant. Thread-safe functions may also be\n> - * called simultaneously with any other reentrant function of the same class\n> - * on the same instance.\n> - *\n> - * - \\anchor thread-bound A **thread-bound** function may be called only from\n> - * the thread that the class instances lives in (see section \\ref\n> - * thread-objects). For instances of classes that do not derive from the\n> - * Object class, this is the thread in which the instance was created. A\n> - * thread-bound function is not thread-safe, and may or may not be reentrant.\n> - *\n> - * Neither reentrancy nor thread-safety, in this context, mean that a function\n> - * may be called simultaneously from the same thread, for instance from a\n> - * callback invoked by the function. This may deadlock and isn't allowed unless\n> - * separately documented.\n> - *\n> - * A class is defined as reentrant, thread-safe or thread-bound if all its\n> - * member functions are reentrant, thread-safe or thread-bound respectively.\n> - * Some member functions may additionally be documented as having additional\n> - * thread-related attributes.\n> - *\n> - * Most classes are reentrant but not thread-safe, as making them fully\n> - * thread-safe would incur locking costs considered prohibitive for the\n> - * expected use cases.\n> */\n> \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 43066BDB13\n\tfor ;\n\tWed, 14 Aug 2024 00:58:03 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 3E895633B5;\n\tWed, 14 Aug 2024 02:58:02 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id EE12E63369\n\tfor ;\n\tWed, 14 Aug 2024 02:57:59 +0200 (CEST)","from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi\n\t[81.175.209.231])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 514437E2;\n\tWed, 14 Aug 2024 02:57:02 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"K0u9J5wt\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723597022;\n\tbh=LTsyAYrcmwCQEonGC8U6RgPeLsKL8KbcoHIubYye3m4=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=K0u9J5wt87aZyBSc+Q0EnSjU4thGZGEylDqlqBMIU/BLC7voKjfw9U72ehCPAXNSh\n\t4na4AmMFMPWXAeAiajtXQIClTj7xYjJjOr1hoRs9CLLbVWFc2G5Fv3WUxcfPT+oSII\n\tZ8MsvdYUT33W74smsQ1T9y4V752lirsxA5NNK5CU=","Date":"Wed, 14 Aug 2024 03:57:35 +0300","From":"Laurent Pinchart ","To":"Daniel Scally ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH v7 1/5] Documentation: Add Thread safety page","Message-ID":"<20240814005735.GK5833@pendragon.ideasonboard.com>","References":"<20240808140948.430419-1-dan.scally@ideasonboard.com>\n\t<20240808140948.430419-2-dan.scally@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20240808140948.430419-2-dan.scally@ideasonboard.com>","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","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]