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

#include "reda/reda_dll.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Doxygen file & module documentation ==================================*/
/*e \file
    \brief Defines the REDAEpoch interface
*/

/*e \defgroup REDAEpochClass REDAEpoch
  \ingroup REDAModule
  \brief used to determine staleness, version counting, and central to
  lockless table.

  That is, multiple threads can concurrently write the epoch.
  Multiple concurrent readers will never see intermediate garbage values.
  We assume  writing an "unsigned int" is atomic on all architectures for now.

  All weakly referenced information has an epoch which is strictly
  monotonically increasing with every change.  If the referer finds that
  his idea of epoch is different than the current epoch, it means that
  his information is stale and therefore should not be used.
*/

/*e \ingroup REDAEpochClass
  @brief Definition of the type
  @todo consider making the epoch the LONGEST int that can be written
  atomically (e.g. long) on every platform
*/
typedef unsigned int REDAEpoch;

/*e \ingroup REDAEpochClass
  @brief Unknown REDAEpoch

  Usually, when an epoch is unknown, the actor should assume the information
  tied to the unknown epoch is stale.  Depending on the usage, it may also
  mean that the caller wants to find the correct latest epoch.
*/
#define REDA_EPOCH_UNKNOWN (0)

/*i \ingroup REDAEpochClass

  For wrap detection.
  WARNING: ASSUMPTION: an unsigned int is at least 32 bits (it's OK
  if it's bigger).
*/
#define REDA_EPOCH_HALF_VALUE ((REDAEpoch) 0x80000000)

/*e \ingroup REDAEpochClass
Tests whether this epoch is greater than the value
@return 1 if true, 0 otherwise
*/
extern REDADllExport int REDAEpoch_isGreater(REDAEpoch me, REDAEpoch value);

/*e \ingroup REDAEpochClass
  Tests whether this epoch is less than the value
  @return 1 if true, 0 otherwise
*/
extern REDADllExport int REDAEpoch_isLess(REDAEpoch me, REDAEpoch value);

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

#include "reda/reda_epoch_impl.h"

#endif /* reda_epoch_h */