{"id":20821,"url":"https://patchwork.libcamera.org/api/1.1/patches/20821/?format=json","web_url":"https://patchwork.libcamera.org/patch/20821/","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":"<20240807142246.331922-1-dan.scally@ideasonboard.com>","date":"2024-08-07T14:22:46","name":"[v6,14/18] Documentation: Add Thread safety page","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"be69c5e099be76369fe5ef304905105d5eebc28c","submitter":{"id":156,"url":"https://patchwork.libcamera.org/api/1.1/people/156/?format=json","name":"Dan Scally","email":"dan.scally@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/20821/mbox/","series":[{"id":4496,"url":"https://patchwork.libcamera.org/api/1.1/series/4496/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=4496","date":"2024-08-07T14:22:46","name":null,"version":6,"mbox":"https://patchwork.libcamera.org/series/4496/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/20821/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/20821/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 072F2C323E\n\tfor ;\n\tWed, 7 Aug 2024 14:23:04 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 936026338D;\n\tWed, 7 Aug 2024 16:23: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 54E5F6337E\n\tfor ;\n\tWed, 7 Aug 2024 16:23:01 +0200 (CEST)","from mail.ideasonboard.com\n\t(cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 372412EC;\n\tWed, 7 Aug 2024 16:22:08 +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=\"mhNs8MAa\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723040528;\n\tbh=S8ViEvDLIj3O2x3InovTx/c4DwOKJ0h/g67XCR0j95Y=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=mhNs8MAao9ULf8HkSu8mb3B1ptk4AnZ0aCAXLhS6h+FWgs3hu2IbEFf4NKrP+l/01\n\tqI5NKAfRFWeZRxFwN2CHM+31323BwxAhaiRb+Po5Vb9aFdtQhTeBcjLQ/33EPqDEbO\n\tgkxeYKCFjqb9Z+0Ll9BdvJ4e0aplL1ZXaAXW6CYs=","From":"Daniel Scally ","To":"libcamera-devel@lists.libcamera.org,\n\tlaurent.pinchart@ideasonboard.com","Cc":"Daniel Scally ","Subject":"[PATCH v6 14/18] Documentation: Add Thread safety page","Date":"Wed, 7 Aug 2024 15:22:46 +0100","Message-Id":"<20240807142246.331922-1-dan.scally@ideasonboard.com>","X-Mailer":"git-send-email 2.34.1","In-Reply-To":"<20240805143654.20870-15-laurent.pinchart@ideasonboard.com>","References":"<20240805143654.20870-15-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":"Move the section of the Thread support page dealing with thread\nsafety to a dedicated .dox file at Documentation/. This is done to\nsupport the splitting of the Documentation into a public and internal\nversion. With a separate page, references can be made to thread\nsafety without having to include the Thread class in the doxygen run.\n\nSigned-off-by: Daniel Scally \n---\nChanges in v6:\n\n\t- Much of the content that dealt with internal implementation was moved\n\t back to its place against the Thread class. The thread safety section\n\t is retained in a separate page, with a single reference to the main\n\t thread support page who's display is conditional on the doxygen\n\t INTERNAL_DOCS directive.\n\nGiven the scope of the changes, I dropped the R-b tags the patch had accumulated\n\nChanges in v5:\n\n\t- None\n\nChanges in v4:\n\n\t- None\n\nChanges in v3:\n\n\t- None\n\nChanges in v2:\n\n\t- 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 62e63968..6e5a3830 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 00000000..d1f8bd37\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 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 /**\n","prefixes":["v6","14/18"]}