[libcamera-devel] [PATCH 17/19] libcamera: pipeline_handler: Implement the threading model

[Niklas Söderlund]

Hi Laurent,

Thanks for your work.

On 2020-01-20 02:24:35 +0200, Laurent Pinchart wrote:
> Document the threading model of the PipelineHandler class (and all its
> derived classes). The model is already enforced by the Camera class, so
> not much is required. As for the Camera class, disconnection is
> currently left out.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

s/Implement/Document/ in the patch subject, whit this fixed,

Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>

> ---
>  src/libcamera/pipeline_handler.cpp | 36 ++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
> 
> diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
> index 3091971d5da0..2ebf73b76e6b 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 0 on success or a negative error code otherwise
>   */
>  
> @@ -343,6 +360,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
>   */
>  
> @@ -358,6 +377,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.
>   */
>  
>  /**
> @@ -370,6 +391,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
>   */
>  
> @@ -380,6 +403,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.
>   */
>  
>  /**
> @@ -396,6 +421,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)
> @@ -422,6 +449,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
>   */
>  
> @@ -438,6 +467,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
>   */
> @@ -460,6 +491,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)
>  {
> @@ -493,6 +526,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,
> @@ -586,6 +621,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
>   */
>  
> -- 
> Regards,
> 
> Laurent Pinchart
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel at lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

-- 
Regards,
Niklas Söderlund