RTI Connext DDS Micro  Version 2.4.8
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
reda_epoch.h
Go to the documentation of this file.
1 /*
2  * FILE: reda_epoch.h - Epoch API
3  *
4  * Copyright 2012-2015 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 04jan2012,tk Written
14  */
15 /*ce
16  * \file
17  */
18 #ifndef reda_epoch_h
19 #define reda_epoch_h
20 
21 #ifndef reda_dll_h
22 #include "reda/reda_dll.h"
23 #endif
24 
25 #ifdef __cplusplus
26 extern "C"
27 {
28 #endif
29 
30 /*ci
31  * \file
32  * \brief Defines the REDA_Epoch interface
33  *
34  * \defgroup REDAEpochClass REDA Epoch
35  * \ingroup REDAModule
36  *
37  * \brief Generic epoch counter
38  *
39  * \details
40  *
41  * Used to determine staleness, version counting, and central to lockless tables.
42  * That is, multiple threads can concurrently write the epoch.
43  * Multiple concurrent readers will never see intermediate garbage values.
44  * We assume writing an "unsigned int" is atomic on all architectures.
45  *
46  * All weakly referenced information has an epoch which is strictly
47  * monotonically increasing with every change. If the referrer finds that
48  * his idea of epoch is different than the current epoch, it means that
49  * his information is stale and therefore should not be used.
50  */
51 
52 /*ci \addtogroup REDAEpochClass
53  * @{
54  */
55 
56 /*ci
57  * \brief Definition of the epoch type
58  */
59 typedef RTI_INT32 REDA_Epoch_T;
60 
61 /*ci
62  * \def REDA_EPOCH_UNKNOWN
63  *
64  * \brief Unknown REDA_Epoch
65  *
66  * \details
67  *
68  * Usually, when an epoch is unknown, the actor should assume the information
69  * tied to the unknown epoch is stale. Depending on the usage, it may also
70  * mean that the caller wants to find the correct latest epoch.
71 */
72 #define REDA_EPOCH_UNKNOWN (0)
73 
74 /*ci
75  * \def REDA_EPOCH_HALF_VALUE
76  *
77  * \brief Constant used for wrap detection. ASSUMPTION: an unsigned
78  * int is at least 32 bits (it's OK
79  * if it's bigger).
80  */
81 #define REDA_EPOCH_HALF_VALUE ((REDA_Epoch)0x80000000)
82 
83 /*ci
84  * \brief Tests whether this epoch is greater than the value
85  *
86  * \param[in] me Epoch to test
87  * \param[in] value Epoch to value to test against
88  *
89  * \return 1 if true, 0 otherwise
90  *
91  * \sa REDA_Epoch_is_less
92  */
93 MUST_CHECK_RETURN REDADllExport RTI_INT32
94 REDA_Epoch_is_greater(REDA_Epoch_T me, REDA_Epoch_T value);
95 
96 #define REDA_Epoch_is_greater(me, value) (me > value)
97 
98 /*ci
99  * \brief Tests whether this epoch is less than the value
100  *
101  * \param[in] me Epoch to test
102  * \param[in] value Epoch to value to test against
103  *
104  * \return 1 if true, 0 otherwise
105  *
106  * \sa REDA_Epoch_is_greater
107  */
108 MUST_CHECK_RETURN REDADllExport RTI_INT32
109 REDA_Epoch_is_less(REDA_Epoch_T me, REDA_Epoch_T value);
110 
111 #define REDA_Epoch_is_less(me, value) (me < value)
112 
113 #ifdef __cplusplus
114 } /* extern "C" */
115 #endif
116 
117 #endif /* reda_epoch_h */
118 
119 /*ci @} */
RTI Connext DDS Micro Version 2.4.8 Copyright © Tue Apr 12 2016 Real-Time Innovations, Inc