Patch Detail
Show a patch.
GET /api/1.1/patches/20823/?format=api
{ "id": 20823, "url": "https://patchwork.libcamera.org/api/1.1/patches/20823/?format=api", "web_url": "https://patchwork.libcamera.org/patch/20823/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/1.1/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": "<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=api", "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=api", "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": "<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 CF191C323E\n\tfor <parsemail@patchwork.libcamera.org>;\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 <libcamera-devel@lists.libcamera.org>;\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 <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Cc": "Daniel Scally <dan.scally@ideasonboard.com>", "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": "<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": "From: Daniel Scally <dan.scally@ideasonboard.com>\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 <dan.scally@ideasonboard.com>\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" ] }