From patchwork Sun May 23 02:31:52 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 12364 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 751F9C3200 for ; Sun, 23 May 2021 02:32:05 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 4DB1F68921; Sun, 23 May 2021 04:32:04 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="e97OAABc"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 9F5CE68911 for ; Sun, 23 May 2021 04:32:01 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 2E03F89A; Sun, 23 May 2021 04:32:01 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1621737121; bh=ekMaN0LjvgaW6Wcf8DnKW8+/k+nO8ZduHf1bqtbnB3Q=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=e97OAABcdu5xFVRimB3Hp9Hvd2ocRgbmDVRRe9imq3AABja0JWxD1kJva7I3/5n58 +OZLrrzgXRLNU40N+BMMBaWnEUd8tACw4eZtGbRF5WI532od6JjFDzorTj//faXard IJ7/sArAqKXKzO/iGVoI7X0gG8//eE4+ivEmHANg= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Sun, 23 May 2021 05:31:52 +0300 Message-Id: <20210523023155.20268-2-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 Subject: [libcamera-devel] [PATCH 1/4] libcamera: thread: Document dispatchMessages() thread-safety requirements X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The Thread class is incorrectly documented as thread-safe, as the dispatchMessages() function isn't thread-safe. Fix the documentation by tagging individual functions as thread-safe as appropriate. Signed-off-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Reviewed-by: Umang Jain Reviewed-by: Hirokazu Honda Reviewed-by: Jacopo Mondi --- src/libcamera/thread.cpp | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/src/libcamera/thread.cpp b/src/libcamera/thread.cpp index 198670de33a2..285b808332e8 100644 --- a/src/libcamera/thread.cpp +++ b/src/libcamera/thread.cpp @@ -229,8 +229,6 @@ ThreadData *ThreadData::current() * called. The event loop dispatches events (messages, notifiers and timers) * sent to the objects living in the thread. This behaviour can be modified by * overriding the run() function. - * - * \context This class is \threadsafe. */ /** @@ -361,6 +359,8 @@ void Thread::finishThread() * * Calling exit() on a thread that reimplements the run() method and doesn't * call exec() will likely have no effect. + * + * \context This function is \threadsafe. */ void Thread::exit(int code) { @@ -383,6 +383,8 @@ void Thread::exit(int code) * utils::duration::max(), the wait never times out. If the thread is not * running the function returns immediately. * + * \context This function is \threadsafe. + * * \return True if the thread has finished, or false if the wait timed out */ bool Thread::wait(utils::duration duration) @@ -412,6 +414,8 @@ bool Thread::wait(utils::duration duration) * started. This method guarantees that it returns true after the start() * method returns, and false after the wait() method returns. * + * \context This function is \threadsafe. + * * \return True if the thread is running, false otherwise */ bool Thread::isRunning() @@ -427,6 +431,7 @@ bool Thread::isRunning() /** * \brief Retrieve the Thread instance for the current thread + * \context This function is \threadsafe. * \return The Thread instance for the current thread */ Thread *Thread::current() @@ -441,6 +446,8 @@ Thread *Thread::current() * The thread ID corresponds to the Linux thread ID (TID) as returned by the * gettid system call. * + * \context This function is \threadsafe. + * * \return The ID of the current thread */ pid_t Thread::currentId() @@ -455,6 +462,8 @@ pid_t Thread::currentId() * This function retrieves the internal event dispatcher for the thread. The * returned event dispatcher is valid until the thread is destroyed. * + * \context This function is \threadsafe. + * * \return Pointer to the event dispatcher */ EventDispatcher *Thread::eventDispatcher() @@ -544,6 +553,10 @@ void Thread::removeMessages(Object *receiver) * This function immediately dispatches all the messages previously posted for * this thread with postMessage() that match the message \a type. If the \a type * is Message::Type::None, all messages are dispatched. + * + * Messages shall only be dispatched from the current thread, typically within + * the thread from the run() function. Calling this function outside of the + * thread results in undefined behaviour. */ void Thread::dispatchMessages(Message::Type type) { From patchwork Sun May 23 02:31:53 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 12365 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 3813DC3200 for ; Sun, 23 May 2021 02:32:06 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 01EA66891F; Sun, 23 May 2021 04:32:05 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="aLudtdmh"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 0D9EA68911 for ; Sun, 23 May 2021 04:32:02 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 8BC428E6; Sun, 23 May 2021 04:32:01 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1621737121; bh=sjECzHXvytrVhD5+5f8Jj7s9oMvnRca65S0EFXMcdSM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=aLudtdmhTCjdi4BM5H4KJQOtfRn3ojGsV2GxBsoiEgOc6eatIPfpEimthgpf0hDcQ 16fD+zcrXN21tNImU+KiRxSBpz8udjmhVG6aDVURaQkaWZe1FEzW3bL01DLJjxWWn3 U8FYlAkZh/oyq0N3HPw8EWoNKqgVCpUReFfpbYqs= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Sun, 23 May 2021 05:31:53 +0300 Message-Id: <20210523023155.20268-3-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 Subject: [libcamera-devel] [PATCH 2/4] libcamera: thread: Enforce dispatchMessages() call context with assert X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The Thread::dispatchMessages() function is meant to be called from within the thread only. Catch incorrect usage with an ASSERT(). Signed-off-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Reviewed-by: Umang Jain Reviewed-by: Hirokazu Honda --- src/libcamera/thread.cpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/libcamera/thread.cpp b/src/libcamera/thread.cpp index 285b808332e8..bc1dcedea0d1 100644 --- a/src/libcamera/thread.cpp +++ b/src/libcamera/thread.cpp @@ -560,6 +560,8 @@ void Thread::removeMessages(Object *receiver) */ void Thread::dispatchMessages(Message::Type type) { + ASSERT(data_ == ThreadData::current()); + MutexLocker locker(data_->messages_.mutex_); std::list> &messages = data_->messages_.list_; From patchwork Sun May 23 02:31:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 12366 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id C3CD9C3200 for ; Sun, 23 May 2021 02:32:06 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 6869D6891E; Sun, 23 May 2021 04:32:06 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Hc0Xmbbe"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 703E368911 for ; Sun, 23 May 2021 04:32:02 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id F35302A8; Sun, 23 May 2021 04:32:01 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1621737122; bh=4DX+fdAAjUoOjofw2CydUwhFYPlKi9X48/oFJfmcoM4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hc0XmbbewOZSlZ9vX3FsgOpk+gvBoa8YOucq/K5kf45/SIAS9QhzzeNc0zWSfyPdI RWVSQ2bzWQSNGIEvOdtF/c8+2k/vA6xtNTWbBSu4Djj3CUKZPCsmEu/in5E7VaWK+k jMumh3aXqmAOoecjNiG3TXVeO8fpclav1g4v3TnM= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Sun, 23 May 2021 05:31:54 +0300 Message-Id: <20210523023155.20268-4-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 Subject: [libcamera-devel] [PATCH 3/4] libcamera: thread: Drop doc of asynchronous signals delivery to applications X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The asynchronous signal delivery mechanism can't be used by application, as it requires libcamera to be aware of the application event loop, which has been dropped a long time ago. Drop the corresponding documentation paragraph. Signed-off-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Reviewed-by: Umang Jain Reviewed-by: Hirokazu Honda --- src/libcamera/thread.cpp | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/libcamera/thread.cpp b/src/libcamera/thread.cpp index bc1dcedea0d1..d59e43966d26 100644 --- a/src/libcamera/thread.cpp +++ b/src/libcamera/thread.cpp @@ -64,14 +64,6 @@ * be overridden by selecting a different connection type when calling * Signal::connect(). * - * Asynchronous signal delivery is used internally in libcamera, but is also - * available to applications if desired. To use this feature, applications - * shall create receiver classes that inherit from the Object class, and - * provide an event loop to the CameraManager as explained above. Note that - * Object instances created by the application are limited to living in the - * application's main thread. Creating Object instances from another thread of - * an application causes undefined behaviour. - * * \section thread-reentrancy Reentrancy and Thread-Safety * * Through the documentation, several terms are used to define how classes and From patchwork Sun May 23 02:31:55 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 12367 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 6F4B5C3200 for ; Sun, 23 May 2021 02:32:07 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 0254E68919; Sun, 23 May 2021 04:32:06 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Fi9tB5no"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id CCCF068911 for ; Sun, 23 May 2021 04:32:02 +0200 (CEST) Received: from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 5F53189A; Sun, 23 May 2021 04:32:02 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1621737122; bh=3Bf8lSVvHl956y2+zY2+0HX7j8Rg7gx5BlxIHgzR2Oc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Fi9tB5noClwh9Rjzlqm9VKiFzyM1qY9I74oIqhYlxggZAYF+9SQ2DHa/c88a3BetF yrnow0RHmsfkBVrWYd9deO22oJWwEd3iw7V2sSUCRkReqarnKKhA6qhq9KprJuiKew ovREtdghOraYzHupuM38a2ClHuVBwOTMY1Z+hQ5c= From: Laurent Pinchart 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 Subject: [libcamera-devel] [PATCH 4/4] libcamera: thread: Document race condition at stop time X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" When a thread stops, messages may be left in its message queue. Document this in details, with a way to force processing of pending messages when the thread is stopped. Signed-off-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Reviewed-by: Umang Jain Reviewed-by: Hirokazu Honda Reviewed-by: Jacopo Mondi --- src/libcamera/object.cpp | 8 ++++++++ src/libcamera/thread.cpp | 44 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/src/libcamera/object.cpp b/src/libcamera/object.cpp index cd83c684b989..5e6b73f9af84 100644 --- a/src/libcamera/object.cpp +++ b/src/libcamera/object.cpp @@ -155,6 +155,10 @@ void Object::deleteLater() * running its event loop the message will not be delivered until the event * loop gets started. * + * Due to their asynchronous nature, threads do not provide any guarantee that + * all posted messages are delivered before the thread is stopped. See + * \ref thread-stop for additional information. + * * \context This function is \threadsafe. */ void Object::postMessage(std::unique_ptr msg) @@ -212,6 +216,10 @@ void Object::message(Message *msg) * are passed untouched. The caller shall ensure that any pointer argument * remains valid until the method is invoked. * + * Due to the asynchronous nature of threads, functions invoked asynchronously + * with the ConnectionTypeQueued type are not guaranteed to be called before + * the thread is stopped. See \ref thread-stop for additional information. + * * \context This function is \threadsafe. * * \return For connection types ConnectionTypeDirect and diff --git a/src/libcamera/thread.cpp b/src/libcamera/thread.cpp index d59e43966d26..91e4737ad032 100644 --- a/src/libcamera/thread.cpp +++ b/src/libcamera/thread.cpp @@ -221,6 +221,47 @@ ThreadData *ThreadData::current() * called. The event loop dispatches events (messages, notifiers and timers) * sent to the objects living in the thread. This behaviour can be modified by * overriding the run() function. + * + * \section thread-stop Stopping Threads + * + * Threads can't be forcibly stopped. Instead, a thread user first requests the + * thread to exit and then waits for the thread's main function to react to the + * request and return, at which points the thread will stop. + * + * For threads running exec(), the exit() function is used to request the thread + * to exit. For threads subclassing the Thread class and implementing a custom + * run() function, a subclass-specific mechanism shall be provided. In either + * case, the wait() function shall be called to wait for the thread to stop. + * + * Due to their asynchronous nature, threads are subject to race conditions when + * they stop. This is of particular importance for messages posted to the thread + * with postMessage() (and the other mechanisms that rely on it, such as + * Object::invokeMethod() or asynchronous signal delivery). To understand the + * issues, three contexts need to be considered: + * + * - The worker is the Thread performing work and being instructed to stop. + * - The controller is the context which instructs the worker thread to stop. + * - The other contexts are any threads other than the worker and controller + * that interact with the worker thread. + * + * Messages posted to the worker thread from the controller context before + * calling exit() are queued to the thread's message queue, and the Thread class + * offers no guarantee that those messages will be processed before the thread + * stops. This allows threads to stop fast. + * + * A thread that requires delivery of messages posted from the controller + * context before exit() should reimplement the run() function and call + * dispatchMessages() after exec(). + * + * Messages posted to the worker thread from the other contexts are asynchronous + * with respect to the exit() call from the controller context. There is no + * guarantee as to whether those messages will be processed or not before the + * thread stops. + * + * Messages that are not processed will stay in the queue, in the exact same way + * as messages posted after the thread has stopped. They will be processed when + * the thread is restarted. If the thread is never restarted, they will be + * deleted without being processed when the Thread instance is destroyed. */ /** @@ -480,6 +521,9 @@ EventDispatcher *Thread::eventDispatcher() * running its event loop the message will not be delivered until the event * loop gets started. * + * When the thread is stopped, posted messages may not have all been processed. + * See \ref thread-stop for additional information. + * * If the \a receiver is not bound to this thread the behaviour is undefined. * * \sa exec()