{"id":20823,"url":"https://patchwork.libcamera.org/api/1.1/patches/20823/?format=json","web_url":"https://patchwork.libcamera.org/patch/20823/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20240807154410.9552-2-laurent.pinchart@ideasonboard.com>","date":"2024-08-07T15:44:06","name":"[v6,1/5] Documentation: Add Thread safety page","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"be69c5e099be76369fe5ef304905105d5eebc28c","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/1.1/people/2/?format=json","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/20823/mbox/","series":[{"id":4497,"url":"https://patchwork.libcamera.org/api/1.1/series/4497/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=4497","date":"2024-08-07T15:44:05","name":"Split libcamera documentation in public and internal APIs","version":6,"mbox":"https://patchwork.libcamera.org/series/4497/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/20823/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/20823/checks/","tags":{},"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 CF191C323E\n\tfor ;\n\tWed, 7 Aug 2024 15:44:37 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 7F737633B3;\n\tWed, 7 Aug 2024 17:44:37 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id E59D963394\n\tfor ;\n\tWed, 7 Aug 2024 17:44:34 +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 C41666AF;\n\tWed, 7 Aug 2024 17:43:41 +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=\"id63i8Yy\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723045422;\n\tbh=tkU0SmKTvcKZCDJur3Yv2G1MUT+pCWPVAma3TwrKoT0=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=id63i8YyRt/np5Aolj4g/S7VCldRIOsSusQC7Naab4XrKuIJ3Y5YqKjSxko4B1Lfm\n\tofgG3zQ9+eHQW/FVhGwKuX9Ee4A0iJQSQI4HnlS8B3RKirc9TOXzek9sMUNn/PND59\n\tr+VLdqOuvqrcupndjAgIINFrczdDWlZKL9KWQPaI=","From":"Laurent Pinchart ","To":"libcamera-devel@lists.libcamera.org","Cc":"Daniel Scally ","Subject":"[PATCH v6 1/5] Documentation: Add Thread safety page","Date":"Wed, 7 Aug 2024 18:44:06 +0300","Message-ID":"<20240807154410.9552-2-laurent.pinchart@ideasonboard.com>","X-Mailer":"git-send-email 2.44.2","In-Reply-To":"<20240807154410.9552-1-laurent.pinchart@ideasonboard.com>","References":"<20240807154410.9552-1-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","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\" "},"content":"From: Daniel Scally \n\nMove the section of the Thread support page dealing with thread safety\nto a dedicated .dox file at Documentation/. This is done to support the\nsplitting of the Documentation into a public and internal version. With\na separate page, references can be made to thread safety without having\nto include the Thread class in the doxygen run.\n\nSigned-off-by: Daniel Scally \n---\nChanges 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\nGiven the scope of the changes, I dropped the R-b tags the patch had\naccumulated\n\nChanges 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","diff":"diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in\nindex 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\ndiff --git a/Documentation/thread-safety.dox b/Documentation/thread-safety.dox\nnew file mode 100644\nindex 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+ * 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+ *\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+ */\ndiff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp\nindex 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","prefixes":["v6","1/5"]}