626172a16b
Source files in libcamera start by a comment block header, which
includes the file name and a one-line description of the file contents.
While the latter is useful to get a quick overview of the file contents
at a glance, the former is mostly a source of inconvenience. The name in
the comments can easily get out of sync with the file name when files
are renamed, and copy & paste during development have often lead to
incorrect names being used to start with.
Readers of the source code are expected to know which file they're
looking it. Drop the file name from the header comment block.
The change was generated with the following script:
----------------------------------------
dirs="include/libcamera src test utils"
declare -rA patterns=(
['c']=' \* '
['cpp']=' \* '
['h']=' \* '
['py']='# '
['sh']='# '
)
for ext in ${!patterns[@]} ; do
files=$(for dir in $dirs ; do find $dir -name "*.${ext}" ; done)
pattern=${patterns[${ext}]}
for file in $files ; do
name=$(basename ${file})
sed -i "s/^\(${pattern}\)${name} - /\1/" "$file"
done
done
----------------------------------------
This misses several files that are out of sync with the comment block
header. Those will be addressed separately and manually.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com>
292 lines
8.9 KiB
C++
292 lines
8.9 KiB
C++
/* SPDX-License-Identifier: LGPL-2.1-or-later */
|
|
/*
|
|
* Copyright (C) 2019, Google Inc.
|
|
*
|
|
* File descriptor wrapper with shared ownership
|
|
*/
|
|
|
|
#include <libcamera/base/shared_fd.h>
|
|
|
|
#include <string.h>
|
|
#include <sys/types.h>
|
|
#include <unistd.h>
|
|
#include <utility>
|
|
|
|
#include <libcamera/base/log.h>
|
|
#include <libcamera/base/unique_fd.h>
|
|
|
|
/**
|
|
* \file base/shared_fd.h
|
|
* \brief File descriptor wrapper
|
|
*/
|
|
|
|
namespace libcamera {
|
|
|
|
LOG_DEFINE_CATEGORY(SharedFD)
|
|
|
|
/**
|
|
* \class SharedFD
|
|
* \brief 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.
|
|
*/
|
|
|
|
/**
|
|
* \brief Create a SharedFD copying a given \a fd
|
|
* \param[in] fd File descriptor
|
|
*
|
|
* Construct a SharedFD from a numerical file descriptor by duplicating the
|
|
* \a fd, and take ownership of the copy. The original \a 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 \a fd is negative, the SharedFD is constructed as invalid and the fd()
|
|
* function will return -1.
|
|
*/
|
|
SharedFD::SharedFD(const int &fd)
|
|
{
|
|
if (fd < 0)
|
|
return;
|
|
|
|
fd_ = std::make_shared<Descriptor>(fd, true);
|
|
if (fd_->fd() < 0)
|
|
fd_.reset();
|
|
}
|
|
|
|
/**
|
|
* \brief Create a SharedFD taking ownership of a given \a fd
|
|
* \param[in] fd File descriptor
|
|
*
|
|
* Construct a SharedFD from a numerical file descriptor by taking ownership of
|
|
* the \a fd. The original \a fd is set to -1 and shall not be touched by the
|
|
* caller anymore. In particular, the caller shall not close the original \a fd
|
|
* manually. The duplicated file descriptor will be closed automatically when
|
|
* all SharedFD instances that reference it are destroyed.
|
|
*
|
|
* If the \a fd is negative, the SharedFD is constructed as invalid and the fd()
|
|
* function will return -1.
|
|
*/
|
|
SharedFD::SharedFD(int &&fd)
|
|
{
|
|
if (fd < 0)
|
|
return;
|
|
|
|
fd_ = std::make_shared<Descriptor>(fd, false);
|
|
/*
|
|
* The Descriptor constructor can't have failed here, as it took over
|
|
* the fd without duplicating it. Just set the original fd to -1 to
|
|
* implement move semantics.
|
|
*/
|
|
fd = -1;
|
|
}
|
|
|
|
/**
|
|
* \brief Create a SharedFD taking ownership of a given UniqueFD \a fd
|
|
* \param[in] fd UniqueFD
|
|
*
|
|
* Construct a SharedFD from UniqueFD by taking ownership of the \a fd. The
|
|
* original \a fd becomes invalid.
|
|
*/
|
|
SharedFD::SharedFD(UniqueFD fd)
|
|
: SharedFD(fd.release())
|
|
{
|
|
}
|
|
|
|
/**
|
|
* \brief Copy constructor, create a SharedFD from a copy of \a other
|
|
* \param[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::SharedFD(const SharedFD &other)
|
|
: fd_(other.fd_)
|
|
{
|
|
}
|
|
|
|
/**
|
|
* \brief Move constructor, create a SharedFD by taking over \a other
|
|
* \param[in] other The other SharedFD
|
|
*
|
|
* Moving a SharedFD moves the reference to the wrapped descriptor owned by
|
|
* \a other to the new SharedFD. The \a 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::SharedFD(SharedFD &&other)
|
|
: fd_(std::move(other.fd_))
|
|
{
|
|
}
|
|
|
|
/**
|
|
* \brief 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.
|
|
*/
|
|
SharedFD::~SharedFD()
|
|
{
|
|
}
|
|
|
|
/**
|
|
* \brief Copy assignment operator, replace the wrapped file descriptor with a
|
|
* copy of \a other
|
|
* \param[in] other The other SharedFD
|
|
*
|
|
* Copying a SharedFD creates a new reference to the wrapped file descriptor
|
|
* owner by \a other. If \a 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.
|
|
*
|
|
* \return A reference to this SharedFD
|
|
*/
|
|
SharedFD &SharedFD::operator=(const SharedFD &other)
|
|
{
|
|
fd_ = other.fd_;
|
|
|
|
return *this;
|
|
}
|
|
|
|
/**
|
|
* \brief Move assignment operator, replace the wrapped file descriptor by
|
|
* taking over \a other
|
|
* \param[in] other The other SharedFD
|
|
*
|
|
* Moving a SharedFD moves the reference to the wrapped descriptor owned by
|
|
* \a other to the new SharedFD. If \a other is invalid, *this will also be
|
|
* invalid. The \a 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.
|
|
*
|
|
* \return A reference to this SharedFD
|
|
*/
|
|
SharedFD &SharedFD::operator=(SharedFD &&other)
|
|
{
|
|
fd_ = std::move(other.fd_);
|
|
|
|
return *this;
|
|
}
|
|
|
|
/**
|
|
* \fn SharedFD::isValid()
|
|
* \brief Check if the SharedFD instance is valid
|
|
* \return True if the SharedFD is valid, false otherwise
|
|
*/
|
|
|
|
/**
|
|
* \fn SharedFD::get()
|
|
* \brief Retrieve the numerical file descriptor
|
|
* \return The numerical file descriptor, which may be -1 if the SharedFD
|
|
* instance is invalid
|
|
*/
|
|
|
|
/**
|
|
* \fn bool operator==(const SharedFD &lhs, const SharedFD &rhs)
|
|
* \brief Compare the owned file descriptors of two SharedFD for equality
|
|
* \param[in] lhs The first SharedFD
|
|
* \param[in] rhs The second SharedFD
|
|
*
|
|
* Two file descriptors are considered equal if they have the same numerical
|
|
* value. File descriptors with different values that both reference the same
|
|
* file (for instance obtained using dup()) are considered not equal.
|
|
*
|
|
* \return True if the two file descriptors are equal, false otherwise
|
|
*/
|
|
|
|
/**
|
|
* \fn bool operator!=(const SharedFD &lhs, const SharedFD &rhs)
|
|
* \brief Compare the owned file descriptors of two SharedFD for equality
|
|
* \param[in] lhs The first SharedFD
|
|
* \param[in] rhs The second SharedFD
|
|
*
|
|
* Two file descriptors are considered equal if they have the same numerical
|
|
* value. File descriptors with different values that both reference the same
|
|
* file (for instance obtained using dup()) are considered not equal.
|
|
*
|
|
* \return True if the two file descriptors are not equal, false otherwise
|
|
*/
|
|
|
|
/**
|
|
* \brief 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.
|
|
*
|
|
* \return A UniqueFD owning a duplicate of the original file descriptor
|
|
*/
|
|
UniqueFD SharedFD::dup() const
|
|
{
|
|
if (!isValid())
|
|
return {};
|
|
|
|
UniqueFD dupFd(::dup(get()));
|
|
if (!dupFd.isValid()) {
|
|
int ret = -errno;
|
|
LOG(SharedFD, Error)
|
|
<< "Failed to dup() fd: " << strerror(-ret);
|
|
}
|
|
|
|
return dupFd;
|
|
}
|
|
|
|
SharedFD::Descriptor::Descriptor(int fd, bool duplicate)
|
|
{
|
|
if (!duplicate) {
|
|
fd_ = fd;
|
|
return;
|
|
}
|
|
|
|
/* Failing to dup() a fd should not happen and is fatal. */
|
|
fd_ = ::dup(fd);
|
|
if (fd_ == -1) {
|
|
int ret = -errno;
|
|
LOG(SharedFD, Fatal)
|
|
<< "Failed to dup() fd: " << strerror(-ret);
|
|
}
|
|
}
|
|
|
|
SharedFD::Descriptor::~Descriptor()
|
|
{
|
|
if (fd_ != -1)
|
|
close(fd_);
|
|
}
|
|
|
|
} /* namespace libcamera */
|