Patch Detail
Show a patch.
GET /api/patches/20821/?format=api
{ "id": 20821, "url": "https://patchwork.libcamera.org/api/patches/20821/?format=api", "web_url": "https://patchwork.libcamera.org/patch/20821/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "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/people/156/?format=api", "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/series/4496/?format=api", "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": "<libcamera-devel-bounces@lists.libcamera.org>", "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 <parsemail@patchwork.libcamera.org>;\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 <libcamera-devel@lists.libcamera.org>;\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 <dan.scally@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org,\n\tlaurent.pinchart@ideasonboard.com", "Cc": "Daniel Scally <dan.scally@ideasonboard.com>", "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": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "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 <dan.scally@ideasonboard.com>\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" ] }