qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/clock/clock_mock.h

/*
 * (c) Copyright, Real-Time Innovations, 2023-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef clock_mock_h
#define clock_mock_h

#include "clock/clock_interface.h"
#include "clock/clock_dll.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @internal
 * \brief Mock clock for testing. Allows the user to set the time.
 */
struct RTIMockClock;

struct RTIMockClockProperty {
    /*
     * If true, the clock is created in a stopped state. If false,
     * the clock is created in a running state.
     */
    RTIBool isStopped;
    /*
     * The kind of clock to create as the underlying clock of the mock
     * clock
     */
    RTIClockKind internalClockKind;
};

#define RTIMockClockProperty_INITIALIZER \
  { \
    RTI_FALSE,               /* isStopped */ \
    RTI_SYSTEM_CLOCK /* internalClockKind */ \
  }

/** @internal
 * \brief Set the time of the mock clock
 *
 * It can be set to a time in the future or the past. The set time is used as
 * the starting point of the clock when the clock is started again. i.e. if the
 * clock is set at time T1 to a time that is 5 seconds in the future, when the
 * user calls start and then calls getTime at time T10, the returned time will
 * be T10+5 seconds.
 *
 * @pre valid mock clock
 * @pre valid time
 * @pre the mock clock is stopped
 *
 * @post the mock clock is set exactly to the specified time.
 *
 * @exception none.
 */
extern RTIClockDllExport RTIBool
RTIMockClock_setTime(struct RTIClock *clock, struct RTINtpTime *now);

/** @internal
 * \brief Advance the time of the mock clock by advanceTime.
 *
 * advanceTIme can be positive or negative. If positive, the time of the clock
 * will be advanced that far into the future and if negative, the clock will be
 * moved to the past.
 *
 * The time that is advanced will be taken into account for all future calls to
 * any of the mock clock APIs. For example, if the clock is advanced by 10
 * seconds at time T1, then a call to getTime at T5 will return time T5+10
 * seconds.
 *
 * @pre valid mock clock
 * @pre valid time
 *
 * @post the mock clock is advanced by the specified time
 *
 * @exception none.
 */
extern RTIClockDllExport RTIBool
RTIMockClock_advance(struct RTIClock *clock, struct RTINtpTime *advanceTime);

/** @internal
 * \brief Advance the time of the mock clock by seconds. The purpose of this
 * function is to be easier to use than RTIMockClock_advance for one-off time
 * changes.
 *
 * seconds can be positive or negative. If positive, the time of the clock
 * will be advanced that far into the future and if negative, the clock will be
 * moved to the past.
 *
 * The time that is advanced will be taken into account for all future calls to
 * any of the mock clock APIs. For example, if the clock is advanced by 10
 * seconds at time T1, then a call to getTime at T5 will return time T5+10
 * seconds.
 *
 * @pre valid mock clock
 * @pre valid time
 *
 * @post the mock clock is advanced by the specified time
 *
 * @exception none.
 *
 * @see RTIMockClock_advance
 */
extern RTIClockDllExport RTIBool
RTIMockClock_advanceSeconds(struct RTIClock *clock, RTI_INT64 seconds);

/** @internal
 * \brief Start the mock clock.
 *
 * @pre valid mock clock
 * @pre the mock clock is stopped
 *
 * @post the mock clock is started
 *
 * @exception none.
 */
extern RTIClockDllExport RTIBool RTIMockClock_start(struct RTIClock *clock);

/** @internal
 * \brief Stop the mock clock
 * @pre valid mock clock
 * @pre the mock clock is not stopped
 *
 * @post the mock clock is stopped and can be advanced or set to a new time
 *
 * @exception none.
 */
extern RTIClockDllExport void RTIMockClock_stop(struct RTIClock *clock);

/** @internal
 * \brief Destroy a previously created mock clock
 *
 * @pre unused system clock
 *
 * @post if valid, made invalid and resource returned.
 *
 * @exception none.
 */
extern RTIClockDllExport void RTIMockClock_delete(struct RTIClock *me);

/** @internal
 * \brief Create a new mock clock
 *
 * @return Pointer to the newly created mock clock on success, NULL otherwise.
 *
 * @see RTIMockClock_delete
 */
extern RTIClockDllExport struct RTIClock *RTIMockClock_new(
        const struct RTIMockClockProperty *property);


#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* clock_mock_h */