/*
 * (c) Copyright, Real-Time Innovations, 2002-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_interface_h
#define clock_interface_h

#include "osapi/osapi_type.h"
#include "osapi/osapi_ntptime.h"

#ifdef __cplusplus
extern "C" {
#endif

struct RTIClock;

/** @internal \file
  \brief pluggable clock interface.
*/

/** @internal \defgroup RTIClockClass RTIClock
 * \ingroup RTIClockModule
 * \brief This is all you need to know to implement your own clock for use
 * by waveworks.
 */

/** @internal \ingroup RTIClockClass
 * \brief Function prototype for getting the current time.
 *
 * @pre Valid clock and space for now.
 *
 * NOTE: Called in time critical loop.
 *
 * @post On success, the current time is stored in the now pointer and an
 * implementation has updated its state (if there are any) based on the
 * time gotten.  On failure, the value in now should be ignored.
 *
 * @param me
 * @param now \b Out. Space to store the new time.
 *
 * @return RTI_TRUE on success, RTI_FALSE otherwise.
 *
 * @exception all implementations should do at least
 * <UL>
 * <LI>RTI_LOG_PRECONDITION_FAILURE
 * <LI>CLOCK_LOG_OS_FAILURE_x
 * <LI>CLOCK_LOG_NEGATIVE_NOW_s
 * </UL>
 * Specific implementations may do more.
 *
 * @mtsafety multi thread safe
 */
typedef RTIBool (
        *RTIClockTimeGetFunction)(struct RTIClock *me, struct RTINtpTime *now);

/** @internal \ingroup RTIClockClass
 *
 * \brief Function prototype for getting the resolution of the clock.
 *
 * @pre Valid clock (casted as the parent) and space for resolution.
 *
 * @post On success, the resolution of the clock is stored in the resolution
 * pointer.  On failure, the value in resolution should be ignored.
 *
 * @param me
 * @param resolution \b Out. Space to store the resolution.
 *
 * @return RTI_TRUE on success, RTI_FALSE otherwise.
 *
 * @exception all implementations should do at least
 * <UL>
 * <LI>RTI_LOG_PRECONDITION_FAILURE
 * </UL>
 * Implementations may do more.
 *
 * @mtsafety multi thread safe
 */
typedef RTIBool (*RTIClockResolutionGetFunction)(
        const struct RTIClock *me,
        struct RTINtpTime *resolution);

/** @internal \ingroup RTIClockClass
 *
 * \brief Function prototype for resetting the clock.
 *
 * @pre Valid clock (casted as the parent).
 *
 * NOTE: May be slow; do not call in time critical loop.
 *
 * @post On success, the clock is reset to the state in which it would be in
 * if newly created.  Any new times provided by the clock after resetting
 * are not guaranteed to be related to any times gotten before resetting.
 *
 * @param clock \b In. "this".
 *
 * @return RTI_TRUE on success, RTI_FALSE otherwise.
 *
 * @exception all implementations should do at least
 * <UL>
 * <LI>RTI_LOG_PRECONDITION_FAILURE
 * </UL>
 * Specific implementations may do more.
 *
 * @mtsafety one thread at a time
 */
typedef RTIBool (*RTIClockResetFunction)(struct RTIClock *me);

/** @internal \ingroup RTIClockClass
 * Parent class of all pluggable clock, which must supply ALL methods.
 */
struct RTIClock {
    /** @internal Function pointer to get time*/
    RTIClockTimeGetFunction getTime;
    /** @internal Function pointer to get clock resolution */
    RTIClockResolutionGetFunction getResolution;
    /** @internal Function pointer to reset clock */
    RTIClockResetFunction reset;
};

typedef enum RTIClockKind {
    /* Wall clock time (since the 1970 epoch) */
    RTI_SYSTEM_CLOCK,
    RTI_MONOTONIC_CLOCK,
    RTI_HIGH_RESOLUTION_CLOCK
} RTIClockKind;

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

#endif /* clock_interface_h */