[PATCH v6 1/5] Documentation: Add Thread safety page

[Laurent Pinchart]

From: Daniel Scally <dan.scally at ideasonboard.com>

Move the section of the Thread support page dealing with thread safety
to a dedicated .dox file at Documentation/. This is done to support the
splitting of the Documentation into a public and internal version. With
a separate page, references can be made to thread safety without having
to include the Thread class in the doxygen run.

Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
---
Changes since v5:

- Much of the content that dealt with internal implementation was moved
  back to its place against the Thread class. The thread safety section
  is retained in a separate page, with a single reference to the main
  thread support page who's display is conditional on the doxygen
  INTERNAL_DOCS directive.

Given the scope of the changes, I dropped the R-b tags the patch had
accumulated

Changes since v1:

- New patch
---
 Documentation/Doxyfile.in       |  4 +++-
 Documentation/thread-safety.dox | 40 +++++++++++++++++++++++++++++++++
 src/libcamera/base/thread.cpp   | 36 -----------------------------
 3 files changed, 43 insertions(+), 37 deletions(-)
 create mode 100644 Documentation/thread-safety.dox

diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
index 62e63968ce62..6e5a3830ec38 100644
--- a/Documentation/Doxyfile.in
+++ b/Documentation/Doxyfile.in
@@ -23,7 +23,8 @@ CASE_SENSE_NAMES       = YES
 QUIET                  = YES
 WARN_AS_ERROR          = @WARN_AS_ERROR@
 
-INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
+INPUT                  = "@TOP_SRCDIR@/Documentation" \
+                         "@TOP_SRCDIR@/include/libcamera" \
                          "@TOP_SRCDIR@/src/ipa/ipu3" \
                          "@TOP_SRCDIR@/src/ipa/libipa" \
                          "@TOP_SRCDIR@/src/libcamera" \
@@ -32,6 +33,7 @@ INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
 
 FILE_PATTERNS          = *.c \
                          *.cpp \
+                         *.dox \
                          *.h
 
 RECURSIVE              = YES
diff --git a/Documentation/thread-safety.dox b/Documentation/thread-safety.dox
new file mode 100644
index 000000000000..d1f8bd37e082
--- /dev/null
+++ b/Documentation/thread-safety.dox
@@ -0,0 +1,40 @@
+/**
+ * \page thread-safety Reentrancy and Thread-Safety
+ *
+ * Through the documentation, several terms are used to define how classes and
+ * their member functions can be used from multiple threads.
+ *
+ * - A **reentrant** function may be called simultaneously from multiple
+ *   threads if and only if each invocation uses a different instance of the
+ *   class. This is the default for all member functions not explictly marked
+ *   otherwise.
+ *
+ * - \anchor thread-safe A **thread-safe** function may be called
+ *   simultaneously from multiple threads on the same instance of a class. A
+ *   thread-safe function is thus reentrant. Thread-safe functions may also be
+ *   called simultaneously with any other reentrant function of the same class
+ *   on the same instance.
+ *
+ * - \anchor thread-bound A **thread-bound** function may be called only from
+ *   the thread that the class instances lives in. A thread-bound function is
+ *   not thread-safe, and may or may not be reentrant.
+ *
+ * \internal
+ *   For more information on the implementation of thread-bound functions, see
+ *   section \ref thread-objects.
+ * \endinternal
+ *
+ * Neither reentrancy nor thread-safety, in this context, mean that a function
+ * may be called simultaneously from the same thread, for instance from a
+ * callback invoked by the function. This may deadlock and isn't allowed unless
+ * separately documented.
+ *
+ * A class is defined as reentrant, thread-safe or thread-bound if all its
+ * member functions are reentrant, thread-safe or thread-bound respectively.
+ * Some member functions may additionally be documented as having additional
+ * thread-related attributes.
+ *
+ * Most classes are reentrant but not thread-safe, as making them fully
+ * thread-safe would incur locking costs considered prohibitive for the
+ * expected use cases.
+ */
diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp
index 72733431a22e..8735670b8a1e 100644
--- a/src/libcamera/base/thread.cpp
+++ b/src/libcamera/base/thread.cpp
@@ -64,42 +64,6 @@
  * receiver's event loop, running in the receiver's thread. This mechanism can
  * be overridden by selecting a different connection type when calling
  * Signal::connect().
- *
- * \section thread-reentrancy Reentrancy and Thread-Safety
- *
- * Through the documentation, several terms are used to define how classes and
- * their member functions can be used from multiple threads.
- *
- * - A **reentrant** function may be called simultaneously from multiple
- *   threads if and only if each invocation uses a different instance of the
- *   class. This is the default for all member functions not explictly marked
- *   otherwise.
- *
- * - \anchor thread-safe A **thread-safe** function may be called
- *   simultaneously from multiple threads on the same instance of a class. A
- *   thread-safe function is thus reentrant. Thread-safe functions may also be
- *   called simultaneously with any other reentrant function of the same class
- *   on the same instance.
- *
- * - \anchor thread-bound A **thread-bound** function may be called only from
- *   the thread that the class instances lives in (see section \ref
- *   thread-objects). For instances of classes that do not derive from the
- *   Object class, this is the thread in which the instance was created. A
- *   thread-bound function is not thread-safe, and may or may not be reentrant.
- *
- * Neither reentrancy nor thread-safety, in this context, mean that a function
- * may be called simultaneously from the same thread, for instance from a
- * callback invoked by the function. This may deadlock and isn't allowed unless
- * separately documented.
- *
- * A class is defined as reentrant, thread-safe or thread-bound if all its
- * member functions are reentrant, thread-safe or thread-bound respectively.
- * Some member functions may additionally be documented as having additional
- * thread-related attributes.
- *
- * Most classes are reentrant but not thread-safe, as making them fully
- * thread-safe would incur locking costs considered prohibitive for the
- * expected use cases.
  */
 
 /**
-- 
Regards,

Laurent Pinchart