libcamera: thread: Document race condition at stop time

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 <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Umang Jain <umang.jain@ideasonboard.com>
Reviewed-by: Hirokazu Honda <hiroh@chromium.org>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>

1 files changed, 8 insertions, 0 deletions

diff --git a/src/libcamera/object.cpp b/src/libcamera/object.cpp
index cd83c684..5e6b73f9 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<Message> 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