libcamera: libcamera::Fence Class Reference

libcamera v0.7.1 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::Fence Class Reference

Synchronization primitive to manage resources. More...

## Public Member Functions
| Fence (UniqueFD fd)
| Create a Fence.
bool | isValid () const
| Check if a Fence is valid.
const UniqueFD & | fd () const
| Retrieve a constant reference to the file descriptor.
UniqueFD | release ()
| Release the ownership of the file descriptor.

## Detailed Description

Synchronization primitive to manage resources.

The Fence class models a synchronization primitive that can be used by applications to explicitly synchronize resource usage, and can be shared by multiple processes.

Fences are most commonly used in association with frame buffers. A FrameBuffer can be associated with a Fence so that the library can wait for the Fence to be signalled before allowing the camera device to actually access the memory area described by the FrameBuffer.

See also
  Request::addBuffer()

By using a fence, applications can then synchronize between frame buffer consumers and producers, as for example a display device and a camera, to guarantee that a new data transfers only happen once the existing frames have been displayed.

A Fence can be realized by different event notification primitives, the most common of which is represented by waiting for read events to happen on a kernel sync file. This is currently the only mechanism supported by libcamera, but others can be implemented by extending or subclassing this class and implementing opportune handling in the core library.

The Fence class is a thin abstraction around a UniqueFD which simply allows to access it as a const reference or to move its ownership to the caller.

The usage of the Fence class allows to abstract the underlying synchronization mechanism in use and implement an interface towards other library components that will not change when new synchronization primitives will be added as fences.

A Fence is constructed with a UniqueFD whose ownership is moved in the Fence. A FrameBuffer can be associated with a Fence by passing it to the Request::addBuffer() function, which will move the Fence into the FrameBuffer itself. Once a Request is queued to the Camera, a preparation phase guarantees that before actually applying the Request to the hardware, all the valid fences of the frame buffers in a Request are correctly signalled. Once a Fence has completed, the library will release the FrameBuffer fence so that application won't be allowed to access it.

An optional timeout can be started while waiting for a fence to complete. If waiting on a Fence fails for whatever reason, the FrameBuffer's fence is not reset and is made available to application for them to handle it, by releasing the Fence to correctly close the underlying UniqueFD.

A failure in waiting for a Fence to complete will result in the Request to complete in failed state.

See also
  Request::prepare()
  PipelineHandler::doQueueRequests()

## Constructor & Destructor Documentation

## ◆ Fence()

libcamera::Fence::Fence | ( | UniqueFD | fd | ) |

Create a Fence.

Parameters

  [in] | fd | The fence file descriptor

The file descriptor ownership is moved to the Fence.

## Member Function Documentation

## ◆ fd()

const UniqueFD & libcamera::Fence::fd | ( |  | ) | const
| inline

Retrieve a constant reference to the file descriptor.

Returns
  A const reference to the fence file descriptor

## ◆ isValid()

bool libcamera::Fence::isValid | ( |  | ) | const
| inline

Check if a Fence is valid.

A Fence is valid if the file descriptor it wraps is valid.

Returns
  True if the Fence is valid, false otherwise

## ◆ release()

UniqueFD libcamera::Fence::release | ( |  | ) |
| inline

Release the ownership of the file descriptor.

Release the ownership of the wrapped file descriptor by returning it to the caller.

Returns
  The wrapper UniqueFD

The documentation for this class was generated from the following files:

- include/libcamera/fence.h
- src/libcamera/fence.cpp