/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2021, Google Inc.
 *
 * fence.cpp - Synchronization fence
 */

#include "libcamera/fence.h"

namespace libcamera {

/**
 *
 * \file libcamera/fence.h
 * \brief Definition of the Fence class
 */

/**
 * \class Fence
 * \brief 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.
 *
 * \sa 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
 * <a href="https://www.kernel.org/doc/html/latest/driver-api/sync_file.html">kernel sync file.</a>
 * 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.
 *
 * \internal
 *
 * 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.
 *
 * \sa Request::prepare()
 * \sa PipelineHandler::doQueueRequests()
 */

/**
 * \brief Create a Fence
 * \param[in] fd The fence file descriptor
 *
 * The file descriptor ownership is moved to the Fence.
 */
Fence::Fence(UniqueFD fd)
	: fd_(std::move(fd))
{
}

/**
 * \fn Fence::isValid()
 * \brief Check if a Fence is valid
 *
 * A Fence is valid if the file descriptor it wraps is valid.
 *
 * \return True if the Fence is valid, false otherwise
 */

/**
 * \fn Fence::fd()
 * \brief Retrieve a constant reference to the file descriptor
 * \return A const reference to the fence file descriptor
 */

/**
 * \fn Fence::release()
 * \brief Release the ownership of the file descriptor
 *
 * Release the ownership of the wrapped file descriptor by returning it to the
 * caller.
 *
 * \return The wrapper UniqueFD
 */

} /* namespace libcamera */