[{"id":30693,"web_url":"https://patchwork.libcamera.org/comment/30693/","msgid":"<172304655411.1687952.8037759623491038645@ping.linuxembedded.co.uk>","date":"2024-08-07T16:02:34","subject":"Re: [PATCH v6 1/5] Documentation: Add Thread safety page","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Quoting Laurent Pinchart (2024-08-07 16:44:06)\n> From: Daniel Scally \n> \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.\n> \n> Signed-off-by: Daniel Scally \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 | 4 +++-\n> Documentation/thread-safety.dox | 40 +++++++++++++++++++++++++++++++++\n> src/libcamera/base/thread.cpp | 36 -----------------------------\n> 3 files changed, 43 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 62e63968ce62..6e5a3830ec38 100644\n> --- a/Documentation/Doxyfile.in\n> +++ b/Documentation/Doxyfile.in\n> @@ -23,7 +23,8 @@ CASE_SENSE_NAMES = YES\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 +33,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 000000000000..d1f8bd37e082\n> --- /dev/null\n> +++ b/Documentation/thread-safety.dox\n> @@ -0,0 +1,40 @@\n> +/**\n> + * \\page thread-safety Reentrancy and Thread-Safety\n> + *\n> + * Through the documentation, several terms are used to define how classes and\n\nThroughout ? But that was already in the previous text.\n\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. A thread-bound function is\n> + * not thread-safe, and may or may not be reentrant.\n> + *\n> + * \\internal\n> + * For more information on the implementation of thread-bound functions, see\n> + * section \\ref thread-objects.\n> + * \\endinternal\n\nWe've \"lost\" the text: \n\n\"\nFor instances of classes that do not derive from the Object class, this\nis the thread in which the instance was created.\n\"\n\nIs this intentional ?\n\n\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> diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp\n> index 72733431a22e..8735670b8a1e 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> /**\n> -- \n> Regards,\n> \n> Laurent Pinchart\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 CE820C323E\n\tfor ;\n\tWed, 7 Aug 2024 16:02:39 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 36CCD6338D;\n\tWed, 7 Aug 2024 18:02:39 +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 8CA036337E\n\tfor ;\n\tWed, 7 Aug 2024 18:02:37 +0200 (CEST)","from pendragon.ideasonboard.com\n\t(cpc89244-aztw30-2-0-cust6594.18-1.cable.virginm.net [86.31.185.195])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 84F422EC;\n\tWed, 7 Aug 2024 18:01:44 +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=\"MLNX/LML\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723046504;\n\tbh=vlDcXDukIdGlkXD5OoXPlWDncIHiCEXtDhVqsWR033A=;\n\th=In-Reply-To:References:Subject:From:Cc:To:Date:From;\n\tb=MLNX/LMLKatC4k+sdLNVilnkvuiv0hQjHHkZw6v99hWakXW2Jam25pzo8kyI+V23F\n\tdsI6us3G43L5i3rsJXF1/JsGS4mfGGt/rN99BFCvflJ9FZwO8EMVRTnp/ozuMdrgUM\n\tn0ne+bK4R0sPIgFZ1rSx1F3wHEDKw1V/jWBBUZRI=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20240807154410.9552-2-laurent.pinchart@ideasonboard.com>","References":"<20240807154410.9552-1-laurent.pinchart@ideasonboard.com>\n\t<20240807154410.9552-2-laurent.pinchart@ideasonboard.com>","Subject":"Re: [PATCH v6 1/5] Documentation: Add Thread safety page","From":"Kieran Bingham ","Cc":"Daniel Scally ","To":"Laurent Pinchart ,\n\tlibcamera-devel@lists.libcamera.org","Date":"Wed, 07 Aug 2024 17:02:34 +0100","Message-ID":"<172304655411.1687952.8037759623491038645@ping.linuxembedded.co.uk>","User-Agent":"alot/0.10","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\" "}}]