state.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_common_libdaq
 * @copyright 2022 ESO - European Southern Observatory
 *
 * @brief Declares `daq::State` and related functions.
 */
#ifndef DAQ_STATE_HPP_
#define DAQ_STATE_HPP_
 
#include <iosfwd>
 
namespace daq {
 
/**
 * Observable states of the data acquisition process.
 *
 * Final states are either Completed* or Aborted*.
 *
 * life-cycle is fully sequential apart from Aborting and Aborted:
 *
 * The states implemented in OCM are:
 *
 *     NotStarted -> Starting -> Acquiring -> Stopping -> Stopped -> <NotScheduled>
 *
 * and the remaining in DPM for executing the merging (handover is done in state NotScheduled):
 *
 *     <NotScheduled> -> Scheduled -> Transferring -> Merging -> Releasing -> Completed*
 *
 * Each state apart from Completed may transition (optionally via Aborting) to Aborted*.
 *
 *     Aborting -> Aborted*.
 *
 *
 * Where the state
 *
 * @ingroup daq_common_libdaq
 */
enum class State {
    /**
     * @name DAQ states handled by OCM.
     */
    /// @{
    /**
     * Initial state of data acquisition.
     */
    NotStarted = 0,
    /**
     * Transitional state between NotStarted and Acquiring when sources have not begun acquiring
     * data yet.
     */
    Starting = 1,
    /**
     * All data sources have reported data acquisition is in progress.
     */
    Acquiring = 2,
    /**
     * Transitional state between Acquiring and Stopped.
     */
    Stopping = 3,
    /**
     * All data sources have reported they have stopped acquiring data.
     */
    Stopped = 4,
 
    /**
     * Before daq is acknowledged by dpm it remains in NotScheduled.
     *
     * OCM may have attempted to schedule merging in this state so no more modifications are allowed
     * from this point (e.g. updating keywords).
     */
    NotScheduled = 10,
 
    /**
     * Transitional state for aborting during acquisition
     */
    AbortingAcquiring = 2001,
    /// @}
 
    /***
     * @name DAQ states that are handled by DPM.
     */
    /// @{
    /**
     * daq is acknowledged by dpm and is scheduled for merging (i.e. the daq is in the
     * backlog).
     */
    Scheduled = 11,
 
    /**
     * Input files are being transferred.
     */
    Transferring = 12,
    /**
     * DAQ is being merged.
     */
    Merging = 13,
 
    /**
     * Releasing Data Product to receivers.
     */
    Releasing = 14,
 
    /**
     * Transitional state for aborting during merging
     */
    AbortingMerging = 2010,
    /// @}
    
    /***
     * @name States common to OCM and DPM
     */
    /// @{
    /**
     * Data acquisition has been aborted by user.
     */
    Aborted = 2000,
    /**
     * Completed DAQ
     */
    Completed = 3000,
    /// @}
};
 
/**
 * Prints state string representation to os.
 *
 * @ingroup daq_common_libdaq
 */
std::ostream& operator<<(std::ostream& os, State state);
 
/**
 * Query whether @a state is in a final state.
 *
 * @returns true if @a state is Completed or Aborted.
 * @returns false otherwise.
 *
 * @ingroup daq_common_libdaq
 */
bool IsFinalState(State state) noexcept;
 
/**
 * Compares states and returns whether @a state1 occurs after @a state2. If states are the same it
 * returns false.
 *
 * This is e.g. useful to decide when an await condition is fulfillled or when to reject a wait
 * condition because will never occur.
 *
 * @returns true if @a state1 occurs after @a state2 in the DAQ life-cycle.
 *
 * @ingroup daq_common_libdaq
 */
bool IsSubsequentState(State state1, State state2) noexcept;
 
}
#endif // #ifndef DAQ_STATE_HPP_