libcamera: libcamera::SharedFD Class Reference

libcamera v0.7.2 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::SharedFD Class Referencefinal

RAII-style wrapper for file descriptors. More...

## Public Member Functions
| SharedFD (const int &fd=-1)
| Create a SharedFD copying a given fd.
| SharedFD (int &&fd)
| Create a SharedFD taking ownership of a given fd.
| SharedFD (UniqueFD fd)
| Create a SharedFD taking ownership of a given UniqueFD fd.
| SharedFD (const SharedFD &other)
| Copy constructor, create a SharedFD from a copy of other.
| SharedFD (SharedFD &&other)
| Move constructor, create a SharedFD by taking over other.
| ~SharedFD ()
| Destroy the SharedFD instance.
SharedFD & | operator= (const SharedFD &other)
| Copy assignment operator, replace the wrapped file descriptor with a copy of other.
SharedFD & | operator= (SharedFD &&other)
| Move assignment operator, replace the wrapped file descriptor by taking over other.
bool | isValid () const
| Check if the SharedFD instance is valid.
int | get () const
| Retrieve the numerical file descriptor.
UniqueFD | dup () const
| Duplicate a SharedFD.

## Detailed Description

RAII-style wrapper for file descriptors.

The SharedFD class provides RAII-style lifetime management of file descriptors with an efficient mechanism for ownership sharing. At its core, an internal Descriptor object wraps a file descriptor (expressed as a signed integer) with an RAII-style interface. The Descriptor is then implicitly shared with all SharedFD instances constructed as copies.

When constructed from a numerical file descriptor, the SharedFD instance either duplicates or takes over the file descriptor:

- The SharedFD(const int &) constructor duplicates the numerical file descriptor and wraps the duplicate in a Descriptor. The caller is responsible for closing the original file descriptor, and the value returned by fd() will be different from the value passed to the constructor.
- The SharedFD(int &&) constructor takes over the numerical file descriptor and wraps it in a Descriptor. The caller shall not touch the original file descriptor once the function returns, and the value returned by fd() will be identical to the value passed to the constructor.

The copy constructor and assignment operator create copies that share the Descriptor, while the move versions of those functions additionally make the other SharedFD invalid. When the last SharedFD that references a Descriptor is destroyed, the file descriptor is closed.

The numerical file descriptor is available through the fd() function. All SharedFD instances created as copies of a SharedFD will report the same fd() value. Callers can perform operations on the fd(), but shall never close it manually.

## Constructor & Destructor Documentation

## ◆ SharedFD() [1/5]

libcamera::SharedFD::SharedFD | ( | const int & | fd = -1 | ) |
| explicit

Create a SharedFD copying a given fd.

Parameters

  [in] | fd | File descriptor

Construct a SharedFD from a numerical file descriptor by duplicating the fd, and take ownership of the copy. The original fd is left untouched, and the caller is responsible for closing it when appropriate. The duplicated file descriptor will be closed automatically when all SharedFD instances that reference it are destroyed.

If the fd is negative, the SharedFD is constructed as invalid and the fd() function will return -1.

## ◆ SharedFD() [2/5]

libcamera::SharedFD::SharedFD | ( | int && | fd | ) |
| explicit

Create a SharedFD taking ownership of a given fd.

Parameters

  [in] | fd | File descriptor

Construct a SharedFD from a numerical file descriptor by taking ownership of the fd. The original fd is set to -1 and shall not be touched by the caller anymore. In particular, the caller shall not close the original fd manually. The duplicated file descriptor will be closed automatically when all SharedFD instances that reference it are destroyed.

If the fd is negative, the SharedFD is constructed as invalid and the fd() function will return -1.

## ◆ SharedFD() [3/5]

libcamera::SharedFD::SharedFD | ( | UniqueFD | fd | ) |
| explicit

Create a SharedFD taking ownership of a given UniqueFD fd.

Parameters

  [in] | fd | UniqueFD

Construct a SharedFD from UniqueFD by taking ownership of the fd. The original fd becomes invalid.

## ◆ SharedFD() [4/5]

libcamera::SharedFD::SharedFD | ( | const SharedFD & | other | ) |

Copy constructor, create a SharedFD from a copy of other.

Parameters

  [in] | other | The other SharedFD

Copying a SharedFD implicitly shares ownership of the wrapped file descriptor. The original SharedFD is left untouched, and the caller is responsible for destroying it when appropriate. The wrapped file descriptor will be closed automatically when all SharedFD instances that reference it are destroyed.

## ◆ SharedFD() [5/5]

libcamera::SharedFD::SharedFD | ( | SharedFD && | other | ) |

Move constructor, create a SharedFD by taking over other.

Parameters

  [in] | other | The other SharedFD

Moving a SharedFD moves the reference to the wrapped descriptor owned by other to the new SharedFD. The other SharedFD is invalidated and its fd() function will return -1. The wrapped file descriptor will be closed automatically when all SharedFD instances that reference it are destroyed.

## ◆ ~SharedFD()

libcamera::SharedFD::~SharedFD | ( |  | ) |

Destroy the SharedFD instance.

Destroying a SharedFD instance releases its reference to the wrapped descriptor, if any. When the last instance that references a wrapped descriptor is destroyed, the file descriptor is automatically closed.

## Member Function Documentation

## ◆ dup()

UniqueFD libcamera::SharedFD::dup | ( |  | ) | const

Duplicate a SharedFD.

Duplicating a SharedFD creates a duplicate of the wrapped file descriptor and returns a UniqueFD that owns the duplicate. The fd() function of the original and the get() function of the duplicate will return different values. The duplicate instance will not be affected by destruction of the original instance or its copies.

Returns
  A UniqueFD owning a duplicate of the original file descriptor

## ◆ get()

int libcamera::SharedFD::get | ( |  | ) | const
| inline

Retrieve the numerical file descriptor.

Returns
  The numerical file descriptor, which may be -1 if the SharedFD instance is invalid

## ◆ isValid()

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

Check if the SharedFD instance is valid.

Returns
  True if the SharedFD is valid, false otherwise

## ◆ operator=() [1/2]

SharedFD & libcamera::SharedFD::operator= | ( | const SharedFD & | other | ) |

Copy assignment operator, replace the wrapped file descriptor with a copy of other.

Parameters

  [in] | other | The other SharedFD

Copying a SharedFD creates a new reference to the wrapped file descriptor owner by other. If other is invalid, *this will also be invalid. The original SharedFD is left untouched, and the caller is responsible for destroying it when appropriate. The wrapped file descriptor will be closed automatically when all SharedFD instances that reference it are destroyed.

Returns
  A reference to this SharedFD

## ◆ operator=() [2/2]

SharedFD & libcamera::SharedFD::operator= | ( | SharedFD && | other | ) |

Move assignment operator, replace the wrapped file descriptor by taking over other.

Parameters

  [in] | other | The other SharedFD

Moving a SharedFD moves the reference to the wrapped descriptor owned by other to the new SharedFD. If other is invalid, *this will also be invalid. The other SharedFD is invalidated and its fd() function will return -1. The wrapped file descriptor will be closed automatically when all SharedFD instances that reference it are destroyed.

Returns
  A reference to this SharedFD

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

- include/libcamera/base/shared_fd.h
- src/libcamera/base/shared_fd.cpp