libcamera: pipeline_handler: Document the threading model

Document the threading model of the PipelineHandler class (and all its
derived classes). The model is already enforced by the Camera class, so
no change in the implementation is required. As for the Camera class,
disconnection is currently left out.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

1 files changed, 36 insertions, 0 deletions

diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
index 5476dbab..22889be4 100644
--- a/src/libcamera/pipeline_handler.cpp
+++ b/src/libcamera/pipeline_handler.cpp
@@ -166,6 +166,8 @@ PipelineHandler::~PipelineHandler()
  * If this function returns true, a new instance of the pipeline handler will
  * be created and its match() function called.
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return true if media devices have been acquired and camera instances
  * created, or false otherwise
  */
@@ -182,6 +184,8 @@ PipelineHandler::~PipelineHandler()
  * device explicitly, it will be automatically released when the pipeline
  * handler is destroyed.
  *
+ * \context This function shall be called from the CameraManager thread.
+ *
  * \return A pointer to the matching MediaDevice, or nullptr if no match is found
  */
 MediaDevice *PipelineHandler::acquireMediaDevice(DeviceEnumerator *enumerator,
@@ -205,6 +209,8 @@ MediaDevice *PipelineHandler::acquireMediaDevice(DeviceEnumerator *enumerator,
  * This method shall not be called from pipeline handler implementation, as the
  * Camera class handles locking directly.
  *
+ * \context This function is \threadsafe.
+ *
  * \return True if the devices could be locked, false otherwise
  * \sa unlock()
  * \sa MediaDevice::lock()
@@ -227,6 +233,8 @@ bool PipelineHandler::lock()
  * This method shall not be called from pipeline handler implementation, as the
  * Camera class handles locking directly.
  *
+ * \context This function is \threadsafe.
+ *
  * \sa lock()
  */
 void PipelineHandler::unlock()
@@ -238,6 +246,7 @@ void PipelineHandler::unlock()
 /**
  * \brief Retrieve the list of controls for a camera
  * \param[in] camera The camera
+ * \context This function is \threadsafe.
  * \return A ControlInfoMap listing the controls support by \a camera
  */
 const ControlInfoMap &PipelineHandler::controls(Camera *camera)
@@ -261,6 +270,10 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  * The intended companion to this is \a configure() which can be used to change
  * the group of streams parameters.
  *
+ * \context This function may be called from any thread and shall be
+ * \threadsafe. It shall not modify the state of the \a camera in the pipeline
+ * handler.
+ *
  * \return A valid CameraConfiguration if the requested roles can be satisfied,
  * or a null pointer otherwise. The ownership of the returned configuration is
  * passed to the caller.
@@ -286,6 +299,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  * instance to each StreamConfiguration entry in the CameraConfiguration using
  * the StreamConfiguration::setStream() method.
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return 0 on success or a negative error code otherwise
  */
 
@@ -316,6 +331,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  *
  * The only intended caller is Camera::exportFrameBuffers().
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return The number of allocated buffers on success or a negative error code
  * otherwise
  */
@@ -344,6 +361,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  *
  * The only intended caller is Camera::start().
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return 0 on success or a negative error code otherwise
  */
 
@@ -359,6 +378,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  * once per stream.
  *
  * The only intended callers are Camera::stop() and Camera::freeFrameBuffers().
+ *
+ * \context This function is called from the CameraManager thread.
  */
 
 /**
@@ -371,6 +392,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  * will in turn be called from the application to indicate that it has
  * configured the streams and is ready to capture.
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return 0 on success or a negative error code otherwise
  */
 
@@ -381,6 +404,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  *
  * This method stops capturing and processing requests immediately. All pending
  * requests are cancelled and complete immediately in an error state.
+ *
+ * \context This function is called from the CameraManager thread.
  */
 
 /**
@@ -397,6 +422,8 @@ const ControlInfoMap &PipelineHandler::controls(Camera *camera)
  * when the pipeline handler is stopped with stop(). Request completion shall be
  * signalled by the pipeline handler using the completeRequest() method.
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return 0 on success or a negative error code otherwise
  */
 int PipelineHandler::queueRequest(Camera *camera, Request *request)
@@ -423,6 +450,8 @@ int PipelineHandler::queueRequest(Camera *camera, Request *request)
  * parameters will be applied to the frames captured in the buffers provided in
  * the request.
  *
+ * \context This function is called from the CameraManager thread.
+ *
  * \return 0 on success or a negative error code otherwise
  */
 
@@ -439,6 +468,8 @@ int PipelineHandler::queueRequest(Camera *camera, Request *request)
  * pipeline handlers a chance to perform any operation that may still be
  * needed. They shall complete requests explicitly with completeRequest().
  *
+ * \context This function shall be called from the CameraManager thread.
+ *
  * \return True if all buffers contained in the request have completed, false
  * otherwise
  */
@@ -461,6 +492,8 @@ bool PipelineHandler::completeBuffer(Camera *camera, Request *request,
  * This method ensures that requests will be returned to the application in
  * submission order, the pipeline handler may call it on any complete request
  * without any ordering constraint.
+ *
+ * \context This function shall be called from the CameraManager thread.
  */
 void PipelineHandler::completeRequest(Camera *camera, Request *request)
 {
@@ -494,6 +527,8 @@ void PipelineHandler::completeRequest(Camera *camera, Request *request)
  * is to be associated with. This is for the V4L2 compatibility layer to map
  * device nodes to Camera instances based on the device number
  * registered by this method in \a devnum.
+ *
+ * \context This function shall be called from the CameraManager thread.
  */
 void PipelineHandler::registerCamera(std::shared_ptr<Camera> camera,
 				     std::unique_ptr<CameraData> data,
@@ -587,6 +622,7 @@ CameraData *PipelineHandler::cameraData(const Camera *camera)
 /**
  * \fn PipelineHandler::name()
  * \brief Retrieve the pipeline handler name
+ * \context This function shall be \threadsafe.
  * \return The pipeline handler name
  */