From patchwork Wed Jan 22 20:57:17 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 2723 Return-Path: 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 2B04B60890 for ; Wed, 22 Jan 2020 21:57:45 +0100 (CET) Received: from pendragon.bb.dnainternet.fi (81-175-216-236.bb.dnainternet.fi [81.175.216.236]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id BE15B2F9 for ; Wed, 22 Jan 2020 21:57:44 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1579726664; bh=XEGGuOsYttLglPAufH/U5dDguG8C6OG9/6uQKqC3CmM=; h=From:To:Subject:Date:In-Reply-To:References:From; b=HpqkYBd+XKDKR0fvohjsaGZDVA68e4ZU09teLY5xW99IK9aq1gQ8UCy3giwH8Q1YO gAetIj2GsdG2KF99X9pCJ0vL96tbBh24YVUNOW8drKSrS85GVGXaxGk61JhkCaC1hb 6vDWDBq+2EoINhODy9V+ECooB21Th56ldME3jdEQ= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Wed, 22 Jan 2020 22:57:17 +0200 Message-Id: <20200122205723.8865-8-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200122205723.8865-1-laurent.pinchart@ideasonboard.com> References: <20200122205723.8865-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 07/13] libcamera: Document thread-safety attributes of core classes 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: , X-List-Received-Date: Wed, 22 Jan 2020 20:57:47 -0000 Define the thread-safety attributes of the classes and methods that are either thread-safe or thread-bound. The CameraManager, Camera and PipelineHandler will be addressed separately. Signed-off-by: Laurent Pinchart Reviewed-by: Niklas Söderlund --- src/libcamera/device_enumerator.cpp | 2 ++ src/libcamera/event_notifier.cpp | 2 ++ src/libcamera/ipc_unixsocket.cpp | 2 ++ src/libcamera/object.cpp | 10 ++++++++-- src/libcamera/thread.cpp | 2 ++ src/libcamera/timer.cpp | 20 ++++++++++++-------- src/libcamera/v4l2_videodevice.cpp | 2 ++ 7 files changed, 30 insertions(+), 10 deletions(-) diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp index a8b5c90f5a5d..64cdc132308a 100644 --- a/src/libcamera/device_enumerator.cpp +++ b/src/libcamera/device_enumerator.cpp @@ -190,6 +190,8 @@ DeviceEnumerator::~DeviceEnumerator() * with a warning message logged, without returning an error. Only errors that * prevent enumeration altogether shall be fatal. * + * \context This function is \threadbound. + * * \return 0 on success or a negative error code otherwise */ diff --git a/src/libcamera/event_notifier.cpp b/src/libcamera/event_notifier.cpp index 4326b0b413e2..a9be686f79ae 100644 --- a/src/libcamera/event_notifier.cpp +++ b/src/libcamera/event_notifier.cpp @@ -99,6 +99,8 @@ EventNotifier::~EventNotifier() * * This function enables or disables the notifier. A disabled notifier ignores * events and does not emit the \ref activated signal. + * + * \context This function is \threadbound. */ void EventNotifier::setEnabled(bool enable) { diff --git a/src/libcamera/ipc_unixsocket.cpp b/src/libcamera/ipc_unixsocket.cpp index eb1a50239188..6e5cab894a93 100644 --- a/src/libcamera/ipc_unixsocket.cpp +++ b/src/libcamera/ipc_unixsocket.cpp @@ -62,6 +62,8 @@ LOG_DEFINE_CATEGORY(IPCUnixSocket) * communication method. The remote side then instantiates a socket, and binds * it to the other side by passing the file descriptor to bind(). At that point * the channel is operation and communication is bidirectional and symmmetrical. + * + * \context This class is \threadbound. */ IPCUnixSocket::IPCUnixSocket() diff --git a/src/libcamera/object.cpp b/src/libcamera/object.cpp index f2a8be172547..99c3bf9a709b 100644 --- a/src/libcamera/object.cpp +++ b/src/libcamera/object.cpp @@ -110,6 +110,8 @@ Object::~Object() * Messages are delivered through the thread's event loop. If the thread is not * running its event loop the message will not be delivered until the event * loop gets started. + * + * \context This function is \threadsafe. */ void Object::postMessage(std::unique_ptr msg) { @@ -162,6 +164,8 @@ void Object::message(Message *msg) * are passed untouched. The caller shall ensure that any pointer argument * remains valid until the method is invoked. * + * \context This function is \threadsafe. + * * \return For connection types ConnectionTypeDirect and * ConnectionTypeBlocking, return the return value of the invoked method. For * connection type ConnectionTypeQueued, return a default-constructed R value. @@ -170,6 +174,7 @@ void Object::message(Message *msg) /** * \fn Object::thread() * \brief Retrieve the thread the object is bound to + * \context This function is \threadsafe. * \return The thread the object is bound to */ @@ -178,8 +183,7 @@ void Object::message(Message *msg) * \param[in] thread The target thread * * This method moves the object and all its children from the current thread to - * the new \a thread. It shall be called from the thread in which the object - * currently lives, otherwise the behaviour is undefined. + * the new \a thread. * * Before the object is moved, a Message::ThreadMoveMessage message is sent to * it. The message() method can be reimplement in derived classes to be notified @@ -187,6 +191,8 @@ void Object::message(Message *msg) * * Moving an object that has a parent is not allowed, and causes undefined * behaviour. + * + * \context This function is thread-bound. */ void Object::moveToThread(Thread *thread) { diff --git a/src/libcamera/thread.cpp b/src/libcamera/thread.cpp index 38e01771111d..1d0a600ab5cc 100644 --- a/src/libcamera/thread.cpp +++ b/src/libcamera/thread.cpp @@ -222,6 +222,8 @@ ThreadData *ThreadData::current() * called. A custom event dispatcher may be installed with * setEventDispatcher(), otherwise a poll-based event dispatcher is used. This * behaviour can be overriden by overloading the run() method. + * + * \context This class is \threadsafe. */ /** diff --git a/src/libcamera/timer.cpp b/src/libcamera/timer.cpp index 4c68883204e8..24da51524efb 100644 --- a/src/libcamera/timer.cpp +++ b/src/libcamera/timer.cpp @@ -67,16 +67,18 @@ Timer::~Timer() * \brief Start or restart the timer with a timeout of \a msec * \param[in] msec The timer duration in milliseconds * - * This method shall be called from the thread the timer is associated with. If - * the timer is already running it will be stopped and restarted. + * If the timer is already running it will be stopped and restarted. + * + * \context This function is \threadbound. */ /** * \brief Start or restart the timer with a timeout of \a duration * \param[in] duration The timer duration in milliseconds * - * This method shall be called from the thread the timer is associated with. If - * the timer is already running it will be stopped and restarted. + * If the timer is already running it will be stopped and restarted. + * + * \context This function is \threadbound. */ void Timer::start(std::chrono::milliseconds duration) { @@ -87,8 +89,9 @@ void Timer::start(std::chrono::milliseconds duration) * \brief Start or restart the timer with a \a deadline * \param[in] deadline The timer deadline * - * This method shall be called from the thread the timer is associated with. If - * the timer is already running it will be stopped and restarted. + * If the timer is already running it will be stopped and restarted. + * + * \context This function is \threadbound. */ void Timer::start(std::chrono::steady_clock::time_point deadline) { @@ -115,8 +118,9 @@ void Timer::start(std::chrono::steady_clock::time_point deadline) * After this function returns the timer is guaranteed not to emit the * \ref timeout signal. * - * This method shall be called from the thread the timer is associated with. If - * the timer is not running this function performs no operation. + * If the timer is not running this function performs no operation. + * + * \context This function is \threadbound. */ void Timer::stop() { diff --git a/src/libcamera/v4l2_videodevice.cpp b/src/libcamera/v4l2_videodevice.cpp index 82267730289d..b874f2384a53 100644 --- a/src/libcamera/v4l2_videodevice.cpp +++ b/src/libcamera/v4l2_videodevice.cpp @@ -403,6 +403,8 @@ const std::string V4L2DeviceFormat::toString() const * * Upon destruction any device left open will be closed, and any resources * released. + * + * \context This class is \threadbound. */ /**