RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
reda_sequenceNumber.h
1 /*
2  * FILE: reda_sequenceNumber_impl.h - Sequence Number API
3  *
4  * Copyright 2012-2014 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  * 06oct2014,eh MICRO-881: Set SEQUENCE_NUMBER_UNKNOWN as {-1,0}
14  * 20apr2012,tk Written
15  */
16 /*ci
17  * \file
18  *
19  * \brief The REDA Sequence number provides an API to manipulate 64 bit
20  * sequence numbers
21  *
22  * \defgroup REDASequenceNumberClass REDA SequenceNumber
23  * \ingroup REDAModule
24  *
25  * \details
26  *
27  * The REDA Sequence number provides an API to manipulate 64 bit
28  * sequence numbers, including comparison and arithmetic operations.
29  *
30  * The implementation does not assume a 64-bit processor architecture,
31  * but rather relies on 32-bit logic on the "low" and "high" part of the
32  * sequence number.
33  */
34 /*ci
35  * \addtogroup REDASequenceNumberClass
36  * @{
37  */
38 #ifndef reda_sequenceNumber_h
39 #define reda_sequenceNumber_h
40 
41 #ifndef reda_dll_h
42 #include "reda/reda_dll.h"
43 #endif
44 #ifndef osapi_types_h
45 #include "osapi/osapi_types.h"
46 #endif
47 
48 #ifdef __cplusplus
49 extern "C"
50 {
51 #endif
52 
53 struct REDA_Buffer;
54 
55 /*ci
56  * \brief internal representation of a 64-bit signed number.
57  */
58 struct REDA_SequenceNumber
59 {
60  /*ci
61  * \brief The most significant part of the sequence number
62  */
63  RTI_INT32 high;
64 
65  /*ci
66  * \brief The least significant part of the sequence number
67  */
68  RTI_UINT32 low;
69 };
70 
71 /*ci
72  * \def REDA_SEQUENCE_NUMBER_HIGH_MAX
73  * \brief Highest, most positive value for the high part of the seq num
74  */
75 #define REDA_SEQUENCE_NUMBER_HIGH_MAX ((RTI_INT32)0x7fffffff)
76 
77 /*ci
78  * \def REDA_SEQUENCE_NUMBER_LOW_MAX
79  * \brief Highest, most positive value for the low part of the seq num
80  */
81 #define REDA_SEQUENCE_NUMBER_LOW_MAX ((RTI_UINT32)0xffffffff)
82 
83 /*ci
84  * \def REDA_SEQUENCE_NUMBER_MAX
85  * \brief Highest, most positive value for the 64-bit sequence number
86  *
87  * \details
88  * Intended to be used as:
89  * \code
90  * struct REDA_SequenceNumber seqNum = REDA_SEQUENCE_NUMBER_MAX;
91  * \endcode
92  */
93 #define REDA_SEQUENCE_NUMBER_MAX {REDA_SEQUENCE_NUMBER_HIGH_MAX, \
94  REDA_SEQUENCE_NUMBER_LOW_MAX}
95 
96 /*ci
97  * \def REDA_SEQUENCE_NUMBER_ZERO
98  *
99  * \brief Zero value for the 64-bit sequence number
100  *
101  * \details
102  *
103  * Intended to be used as:
104  * \code
105  * struct REDA_SequenceNumber seqNum = REDA_SEQUENCE_NUMBER_ZERO;
106  * \endcode
107  */
108 #define REDA_SEQUENCE_NUMBER_ZERO {0, 0}
109 
110 /*ci
111  * \def REDA_SEQUENCE_NUMBER_UNKNOWN
112  *
113  * \brief Unknown value (-1) for the 64-bit sequence number
114  *
115  * \details
116  *
117  * Intended to be used as:
118  * \code
119  * struct REDA_SequenceNumber seqNum = REDA_SEQUENCE_NUMBER_UNKNOWN;
120  * \endcode
121  *
122  */
123 #define REDA_SEQUENCE_NUMBER_UNKNOWN \
124  {(RTI_INT32)0xffffffff, (RTI_UINT32)0}
125 
126 /*ci
127  *\brief Reset a sequence number to zero.
128  *
129  *\details
130  *
131  * Reset a sequence number to zero. It is safer and more portable than setting
132  * the individual fields.
133  *
134  * \param[in] me Sequence number to set to zero
135  */
136 REDADllExport void
137 REDA_SequenceNumber_set_zero(struct REDA_SequenceNumber *me);
138 
139 /*ci
140  *\brief Set a sequence number to the maximum value.
141  *
142  *\details
143  *
144  * Set a sequence number to the maximum value. It is safer and more
145  * portable than setting the individual fields.
146  *
147  * \param[in] me Sequence number to set to max
148  */
149 REDADllExport void
150 REDA_SequenceNumber_set_maximum(struct REDA_SequenceNumber *me);
151 
152 /*ci
153  *\brief Compare two sequence numbers.
154  *
155  * \details
156  *
157  * Compare two sequences
158  *
159  * \param[in] me Left side of comparison
160  * \param[in] sn Right side of comparison
161  *
162  *\return
163  * <UL>
164  * <LI>If me > sn then return 1.
165  * <LI>If me < sn then return -1.
166  * <LI>If me == sn then return 0.
167  * </UL>
168  */
169 MUST_CHECK_RETURN REDADllExport RTI_INT32
170 REDA_SequenceNumber_compare(const struct REDA_SequenceNumber *me,
171  const struct REDA_SequenceNumber *sn);
172 
173 /*ci
174  * \brief Test if a sequence number is unknown.
175  *
176  * \param[in] me Sequence number to test
177  *
178  * \return RTI_TRUE if sequence number is unknown, RTI_FALSE otherwise
179  */
180 REDADllExport RTI_BOOL
181 REDA_SequenceNumber_is_unknown(const struct REDA_SequenceNumber *me);
182 
183 /*ci
184  * \brief Test if a sequence number is zero.
185  *
186  * \param[in] me Sequence number to test
187  *
188  * \return RTI_TRUE if sequence number is zero, RTI_FALSE otherwise
189  */
190 REDADllExport RTI_BOOL
191 REDA_SequenceNumber_is_zero(const struct REDA_SequenceNumber *me);
192 
193 /*ci
194  * \brief Add two sequence numbers.
195  *
196  * \details
197  *
198  * Add two sequence numbers as sn1 + sn2.
199  *
200  * \param[out] answer sn1 + sn2
201  * \param[in] sn1 Sequence number 1 to add
202  * \param[in] sn2 Sequence number 2 to add
203  *
204  * \return On return answer = sn1 + sn2
205  */
206 REDADllExport void
207 REDA_SequenceNumber_add(struct REDA_SequenceNumber *answer,
208  const struct REDA_SequenceNumber *sn1,
209  const struct REDA_SequenceNumber *sn2);
210 
211 /*ci
212  * \brief Subtract two sequence numbers.
213  *
214  * \details
215  *
216  * Subtract two sequence numbers as sn1 - sn2.
217  *
218  * \param[out] answer sn1 - sn2
219  * \param[in] sn1 Sequence number 1 to subtract from
220  * \param[in] sn2 Sequence number to subtract
221  *
222  * \return On return answer = sn1 - sn2
223  */
224 REDADllExport void
225 REDA_SequenceNumber_subtract(struct REDA_SequenceNumber *answer,
226  const struct REDA_SequenceNumber *sn1,
227  const struct REDA_SequenceNumber *sn2);
228 
229 /*ci
230  * \brief Increment a sequence number by one.
231  *
232  * \details
233  *
234  * Increment a sequence number by one.
235  *
236  * \param[in] me Sequence number to increment
237  *
238  * \sa \ref REDA_SequenceNumber_minusminus
239  */
240 REDADllExport void
241 REDA_SequenceNumber_plusplus(struct REDA_SequenceNumber *me);
242 
243 /*ci
244  * \brief Decrement a sequence number by one.
245  *
246  * \details
247  *
248  * Decrement a sequence number by one.
249  *
250  * \param[in] me Sequence number to decrement by 1
251  *
252  * \sa \ref REDA_SequenceNumber_plusplus
253  */
254 REDADllExport void
255 REDA_SequenceNumber_minusminus(struct REDA_SequenceNumber *me);
256 
257 /*ci
258  * \brief Increment a sequence number by another sequence number.
259  *
260  * \details
261  *
262  * Increment a sequence number with the value of another sequence number.
263  *
264  * \param[in] me Sequence number to increment
265  * \param[in] sn Sequence number to increment by
266  *
267  * \sa \ref REDA_SequenceNumber_plusplus
268  */
269 REDADllExport void
270 REDA_SequenceNumber_increment(struct REDA_SequenceNumber *me,
271  const struct REDA_SequenceNumber *sn);
272 
273 /*ci
274  * \brief Decrement a sequence number by another sequence number.
275  *
276  * \details
277  *
278  * Decrement a sequence number with the value of another sequence number.
279  *
280  * \param[in] me Sequence number to decrement
281  * \param[in] sn Sequence number to decrement by
282  *
283  * \sa \ref REDA_SequenceNumber_increment
284  */
285 REDADllExport void
286 REDA_SequenceNumber_decrement(struct REDA_SequenceNumber *me,
287  const struct REDA_SequenceNumber *sn);
288 
289 /*ci
290  * \brief Find the maximum of two sequence numbers
291  *
292  * \details
293  *
294  * Return the maximum of two sequence numbers in answer
295  *
296  * \param[out] answer max(sn1,sn2)
297  * \param[in] sn1 Sequence number 1
298  * \param[in] sn2 Sequence number 2 to compare against
299  *
300  * \return On return answer = max(sn1,sn2)
301  *
302  * \sa \ref REDA_SequenceNumber_min
303  */
304 REDADllExport void
305 REDA_SequenceNumber_max(struct REDA_SequenceNumber *answer,
306  const struct REDA_SequenceNumber *sn1,
307  const struct REDA_SequenceNumber *sn2);
308 
309 /*ci
310  * \brief Find the minimum of two sequence numbers
311  *
312  * \details
313  *
314  * Return the minimum of two sequence numbers in answer
315  *
316  * \param[out] answer min(sn1,sn2)
317  * \param[in] sn1 Sequence number 1
318  * \param[in] sn2 Sequence number 2 to compare against
319  *
320  * \return On return answer = min(sn1,sn2)
321  *
322  * \sa \ref REDA_SequenceNumber_max
323  */
324 REDADllExport void
325 REDA_SequenceNumber_min(struct REDA_SequenceNumber *answer,
326  const struct REDA_SequenceNumber *sn1,
327  const struct REDA_SequenceNumber *sn2);
328 
329 #ifdef __cplusplus
330 } /* extern "C" */
331 #endif
332 
333 /* pick up hidden performance boosting macros and optimizations */
334 #include "reda/reda_sequenceNumber_impl.h"
335 
336 #endif /* reda_sequenceNumber_h */
337 
338 /*ci @} */
339 
RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc