From 89503199e8d09ac17e6d2dde7715a843ede77e5c Mon Sep 17 00:00:00 2001
From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Date: Sun, 19 Jan 2020 02:54:23 +0200
Subject: libcamera: Document thread-safety attributes of core classes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
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 <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
---
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 a8b5c90f..64cdc132 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 4326b0b4..a9be686f 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 eb1a5023..6e5cab89 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 f2a8be17..99c3bf9a 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<Message> 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 38e01771..1d0a600a 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 4c688832..24da5152 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 82267730..b874f238 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.
*/
/**
--
cgit v1.2.1