Patch Detail
Show a patch.
GET /api/patches/12367/?format=api
{ "id": 12367, "url": "https://patchwork.libcamera.org/api/patches/12367/?format=api", "web_url": "https://patchwork.libcamera.org/patch/12367/", "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": "<20210523023155.20268-5-laurent.pinchart@ideasonboard.com>", "date": "2021-05-23T02:31:55", "name": "[libcamera-devel,4/4] libcamera: thread: Document race condition at stop time", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "99dab44d94de833eed253232ee996cbc347511a9", "submitter": { "id": 2, "url": "https://patchwork.libcamera.org/api/people/2/?format=api", "name": "Laurent Pinchart", "email": "laurent.pinchart@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/12367/mbox/", "series": [ { "id": 2049, "url": "https://patchwork.libcamera.org/api/series/2049/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=2049", "date": "2021-05-23T02:31:51", "name": "libcamera: thread: Documentation fixes and enhancements", "version": 1, "mbox": "https://patchwork.libcamera.org/series/2049/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/12367/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/12367/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 6F4B5C3200\n\tfor <parsemail@patchwork.libcamera.org>;\n\tSun, 23 May 2021 02:32:07 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 0254E68919;\n\tSun, 23 May 2021 04:32:06 +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 CCCF068911\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tSun, 23 May 2021 04:32:02 +0200 (CEST)", "from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 5F53189A;\n\tSun, 23 May 2021 04:32:02 +0200 (CEST)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"Fi9tB5no\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1621737122;\n\tbh=3Bf8lSVvHl956y2+zY2+0HX7j8Rg7gx5BlxIHgzR2Oc=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=Fi9tB5noClwh9Rjzlqm9VKiFzyM1qY9I74oIqhYlxggZAYF+9SQ2DHa/c88a3BetF\n\tyrnow0RHmsfkBVrWYd9deO22oJWwEd3iw7V2sSUCRkReqarnKKhA6qhq9KprJuiKew\n\tovREtdghOraYzHupuM38a2ClHuVBwOTMY1Z+hQ5c=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Sun, 23 May 2021 05:31:55 +0300", "Message-Id": "<20210523023155.20268-5-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.28.1", "In-Reply-To": "<20210523023155.20268-1-laurent.pinchart@ideasonboard.com>", "References": "<20210523023155.20268-1-laurent.pinchart@ideasonboard.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [PATCH 4/4] libcamera: thread: Document race\n\tcondition at stop time", "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": "When a thread stops, messages may be left in its message queue. Document\nthis in details, with a way to force processing of pending messages when\nthe thread is stopped.\n\nSigned-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n---\n src/libcamera/object.cpp | 8 ++++++++\n src/libcamera/thread.cpp | 44 ++++++++++++++++++++++++++++++++++++++++\n 2 files changed, 52 insertions(+)", "diff": "diff --git a/src/libcamera/object.cpp b/src/libcamera/object.cpp\nindex cd83c684b989..5e6b73f9af84 100644\n--- a/src/libcamera/object.cpp\n+++ b/src/libcamera/object.cpp\n@@ -155,6 +155,10 @@ void Object::deleteLater()\n * running its event loop the message will not be delivered until the event\n * loop gets started.\n *\n+ * Due to their asynchronous nature, threads do not provide any guarantee that\n+ * all posted messages are delivered before the thread is stopped. See\n+ * \\ref thread-stop for additional information.\n+ *\n * \\context This function is \\threadsafe.\n */\n void Object::postMessage(std::unique_ptr<Message> msg)\n@@ -212,6 +216,10 @@ void Object::message(Message *msg)\n * are passed untouched. The caller shall ensure that any pointer argument\n * remains valid until the method is invoked.\n *\n+ * Due to the asynchronous nature of threads, functions invoked asynchronously\n+ * with the ConnectionTypeQueued type are not guaranteed to be called before\n+ * the thread is stopped. See \\ref thread-stop for additional information.\n+ *\n * \\context This function is \\threadsafe.\n *\n * \\return For connection types ConnectionTypeDirect and\ndiff --git a/src/libcamera/thread.cpp b/src/libcamera/thread.cpp\nindex d59e43966d26..91e4737ad032 100644\n--- a/src/libcamera/thread.cpp\n+++ b/src/libcamera/thread.cpp\n@@ -221,6 +221,47 @@ ThreadData *ThreadData::current()\n * called. The event loop dispatches events (messages, notifiers and timers)\n * sent to the objects living in the thread. This behaviour can be modified by\n * overriding the run() function.\n+ *\n+ * \\section thread-stop Stopping Threads\n+ *\n+ * Threads can't be forcibly stopped. Instead, a thread user first requests the\n+ * thread to exit and then waits for the thread's main function to react to the\n+ * request and return, at which points the thread will stop.\n+ *\n+ * For threads running exec(), the exit() function is used to request the thread\n+ * to exit. For threads subclassing the Thread class and implementing a custom\n+ * run() function, a subclass-specific mechanism shall be provided. In either\n+ * case, the wait() function shall be called to wait for the thread to stop.\n+ *\n+ * Due to their asynchronous nature, threads are subject to race conditions when\n+ * they stop. This is of particular importance for messages posted to the thread\n+ * with postMessage() (and the other mechanisms that rely on it, such as\n+ * Object::invokeMethod() or asynchronous signal delivery). To understand the\n+ * issues, three contexts need to be considered:\n+ *\n+ * - The worker is the Thread performing work and being instructed to stop.\n+ * - The controller is the context which instructs the worker thread to stop.\n+ * - The other contexts are any threads other than the worker and controller\n+ * that interact with the worker thread.\n+ *\n+ * Messages posted to the worker thread from the controller context before\n+ * calling exit() are queued to the thread's message queue, and the Thread class\n+ * offers no guarantee that those messages will be processed before the thread\n+ * stops. This allows threads to stop fast.\n+ *\n+ * A thread that requires delivery of messages posted from the controller\n+ * context before exit() should reimplement the run() function and call\n+ * dispatchMessages() after exec().\n+ *\n+ * Messages posted to the worker thread from the other contexts are asynchronous\n+ * with respect to the exit() call from the controller context. There is no\n+ * guarantee as to whether those messages will be processed or not before the\n+ * thread stops.\n+ *\n+ * Messages that are not processed will stay in the queue, in the exact same way\n+ * as messages posted after the thread has stopped. They will be processed when\n+ * the thread is restarted. If the thread is never restarted, they will be\n+ * deleted without being processed when the Thread instance is destroyed.\n */\n \n /**\n@@ -480,6 +521,9 @@ EventDispatcher *Thread::eventDispatcher()\n * running its event loop the message will not be delivered until the event\n * loop gets started.\n *\n+ * When the thread is stopped, posted messages may not have all been processed.\n+ * See \\ref thread-stop for additional information.\n+ *\n * If the \\a receiver is not bound to this thread the behaviour is undefined.\n *\n * \\sa exec()\n", "prefixes": [ "libcamera-devel", "4/4" ] }