RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
reda_sequence.h
1 /*
2  * FILE: reda_sequence.h - Sequence API
3  *
4  * Copyright 2008-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  * 19jul2013,as Added support for C++
14  * 03jun2013,kaj MICRO-502 support for string sequences req. max string length
15  * 20oct2008,tk Written
16  */
17 /*ci
18  * \file
19  *
20  * \brief The REDA Sequence API provides a strongly typed vector API.
21  *
22  * \defgroup REDASequenceClass REDA Sequence
23  * \ingroup REDAModule
24  *
25  * \details
26  *
27  * The REDA sequence API provides a strongly typed API to manage variable
28  * size vectors/arrays of the same type. The typing is achieved by encapsulating
29  * generic function in a typed wrapper using macro's. The documentation
30  * is for the generic functions.
31  */
32 #ifndef reda_sequence_h
33 #define reda_sequence_h
34 
35 /*ci
36  * \addtogroup REDASequenceClass
37  * @{
38  */
39 #ifndef reda_dll_h
40 #include "reda/reda_dll.h"
41 #endif
42 #ifndef osapi_types_h
43 #include "osapi/osapi_types.h"
44 #endif
45 
46 #ifdef __cplusplus
47 extern "C"
48 {
49 #endif
50 
51 #define REDA_DEFINE_SEQUENCE_MEMBERS(_TSeq,_T) \
52 _T* _contiguous_buffer;\
53 RTI_INT32 _maximum;\
54 RTI_INT32 _length;\
55 RTI_INT32 _element_size;\
56 RTI_UINT8 _flags; \
57 void *_token1; \
58 void *_token2;
59 
60 /*
61  * Define methods for C++ Sequence class if header
62  * is included when compiling with C++ compiler
63  */
64 #ifdef RTI_CPP
65 
66 #ifdef RTI_CERT
67 #define REDA_DEFINE_SEQUENCE_OVERLOADED_METHODS(_TSeq,_T)\
68 private: \
69  _TSeq(const _TSeq& seq); \
70  _TSeq& operator=(const _TSeq& src_seq);
71 #else
72 #define REDA_DEFINE_SEQUENCE_OVERLOADED_METHODS(_TSeq,_T)\
73 public: \
74  _TSeq(const _TSeq& seq); \
75  _TSeq& operator=(const _TSeq& src_seq);
76 #endif
77 
78 #define REDA_DEFINE_SEQUENCE_METHODS(_TSeq,_T)\
79 public:\
80  RTI_INT32 maximum() const; \
81  bool maximum(RTI_INT32 new_max); \
82  RTI_INT32 length() const; \
83  bool length(RTI_INT32 new_length); \
84  _T* get_reference(RTI_INT32 i); \
85  bool copy(const _TSeq& src_seq); \
86  bool is_equal(const _TSeq& other); \
87  bool loan_contiguous(void* buffer, RTI_INT32 new_length, RTI_INT32 new_max); \
88  bool loan_discontiguous(void* buffer, RTI_INT32 new_length, RTI_INT32 new_max); \
89  bool unloan(); \
90  bool has_ownership(); \
91  _T* get_buffer() const; \
92  bool set_buffer(_T* buffer); \
93  bool has_discontiguous_buffer(); \
94  void set_token(void *token1,void *token2); \
95  void get_token(void **token1,void **token2); \
96  _TSeq();\
97  ~_TSeq();\
98 REDA_DEFINE_SEQUENCE_OVERLOADED_METHODS(_TSeq,_T)
99 
100 #else
101 #define REDA_DEFINE_SEQUENCE_METHODS(_TSeq,_T)
102 #endif
103 
104 #if defined(RTI_WIN32) || defined(RTI_WINCE30)
105 #ifdef RTI_EXPORT_REDA_SEQUENCE
106 #ifdef REDADllExport
107 #undef REDADllExport
108 #endif
109 #define REDADllExport __declspec( dllexport )
110 #endif
111 #endif
112 
113 #define REDA_DEFINE_SEQUENCE_STRUCT(_TSeq,_T) \
114 struct REDADllExport _TSeq {\
115 REDA_DEFINE_SEQUENCE_MEMBERS(_TSeq,_T)\
116 \
117 REDA_DEFINE_SEQUENCE_METHODS(_TSeq,_T)\
118 \
119 };
120 
121 #define REDA_DEFINE_SEQUENCE_IN_C(TSeq, T) \
122 REDADllExport \
123 RTI_BOOL TSeq ## _initialize(struct TSeq* self); \
124  \
125 REDADllExport \
126 RTI_BOOL TSeq ## _finalize(struct TSeq* self); \
127  \
128 REDADllExport \
129 RTI_INT32 TSeq ## _get_maximum(const struct TSeq* self); \
130  \
131 REDADllExport \
132 RTI_BOOL TSeq ## _set_maximum(struct TSeq* self, RTI_INT32 new_max); \
133  \
134 REDADllExport \
135 RTI_INT32 TSeq ## _get_length(const struct TSeq *self); \
136  \
137 REDADllExport \
138 RTI_BOOL TSeq ## _set_length(struct TSeq *self, RTI_INT32 new_length);\
139  \
140 REDADllExport \
141 T* TSeq ## _get_reference(const struct TSeq* self, RTI_INT32 i); \
142  \
143 REDADllExport \
144 struct TSeq* TSeq ## _copy(struct TSeq* self, const struct TSeq* src); \
145  \
146 REDADllExport \
147 RTI_BOOL TSeq ## _is_equal(const struct TSeq* self, const struct TSeq* src); \
148  \
149 REDADllExport \
150 RTI_BOOL TSeq ## _loan_contiguous(struct TSeq* self, void *buffer, \
151  RTI_INT32 new_length, RTI_INT32 new_max); \
152  \
153 REDADllExport \
154 RTI_BOOL TSeq ## _loan_discontiguous(struct TSeq* self, void *buffer, \
155  RTI_INT32 new_length, RTI_INT32 new_max); \
156  \
157 REDADllExport \
158 RTI_BOOL TSeq ## _unloan(struct TSeq *self); \
159 \
160 REDADllExport \
161 RTI_BOOL TSeq ## _has_ownership(const struct TSeq* self); \
162  \
163 REDADllExport \
164 T* TSeq ## _get_buffer(const struct TSeq* self); \
165 \
166 REDADllExport \
167 RTI_BOOL TSeq ## _set_buffer(struct TSeq* self, T *buffer); \
168 \
169 REDADllExport \
170 RTI_BOOL TSeq ## _has_discontiguous_buffer(const struct TSeq* self); \
171 \
172 REDADllExport \
173 void TSeq ## _set_token(struct TSeq* self, void *token1,void *token2); \
174 \
175 REDADllExport \
176 void TSeq ## _get_token(struct TSeq* self, void **token1,void **token2);
177 
178 #define REDA_DEFINE_SEQUENCE(_TSeq,_T) \
179 REDA_DEFINE_SEQUENCE_STRUCT(_TSeq,_T) \
180 REDA_DEFINE_SEQUENCE_IN_C(_TSeq,_T)
181 
182 #define REDA_DEFINE_STRING_SEQUENCE_IN_C(TSeq, T) \
183 REDADllExport \
184 RTI_BOOL TSeq ## _initialize(struct TSeq* self); \
185  \
186 REDADllExport \
187 RTI_BOOL TSeq ## _finalize(struct TSeq* self); \
188  \
189 REDADllExport \
190 RTI_INT32 TSeq ## _get_maximum(const struct TSeq* self); \
191  \
192 REDADllExport \
193 RTI_BOOL TSeq ## _set_maximum(struct TSeq* self, RTI_INT32 new_max, \
194  RTI_UINT32 max_str_len); \
195  \
196 REDADllExport \
197 RTI_INT32 TSeq ## _get_length(const struct TSeq *self); \
198  \
199 REDADllExport \
200 RTI_BOOL TSeq ## _set_length(struct TSeq *self, RTI_INT32 new_length);\
201  \
202 REDADllExport \
203 T* TSeq ## _get_reference(const struct TSeq* self, RTI_INT32 i); \
204  \
205 REDADllExport \
206 struct TSeq* TSeq ## _copy(struct TSeq* self, const struct TSeq* src, \
207  RTI_UINT32 max_str_len); \
208  \
209 REDADllExport \
210 RTI_BOOL TSeq ## _is_equal(const struct TSeq* self, const struct TSeq* src); \
211  \
212 REDADllExport \
213 RTI_BOOL TSeq ## _loan_contiguous(struct TSeq* self, void *buffer, \
214  RTI_INT32 new_length, RTI_INT32 new_max); \
215  \
216 REDADllExport \
217 RTI_BOOL TSeq ## _loan_discontiguous(struct TSeq* self, void *buffer, \
218  RTI_INT32 new_length, RTI_INT32 new_max); \
219  \
220 REDADllExport \
221 RTI_BOOL TSeq ## _unloan(struct TSeq *self); \
222 \
223 REDADllExport \
224 RTI_BOOL TSeq ## _has_ownership(const struct TSeq* self); \
225  \
226 REDADllExport \
227 T* TSeq ## _get_buffer(const struct TSeq* self); \
228 \
229 REDADllExport \
230 RTI_BOOL TSeq ## _set_buffer(struct TSeq* self, T *buffer); \
231 \
232 REDADllExport \
233 RTI_BOOL TSeq ## _has_discontiguous_buffer(const struct TSeq* self); \
234 \
235 REDADllExport \
236 void TSeq ## _set_token(struct TSeq* self, void *token1,void *token2); \
237 \
238 REDADllExport \
239 void TSeq ## _get_token(struct TSeq* self, void **token1,void **token2);
240 
241 #define REDA_DEFINE_STRING_SEQUENCE(_TSeq,_T) \
242 REDA_DEFINE_SEQUENCE_STRUCT(_TSeq,_T) \
243 REDA_DEFINE_STRING_SEQUENCE_IN_C(_TSeq,_T)
244 
245 #define REDA_DEFINE_SEQUENCE_INITIALIZER(t_) \
246 { NULL,0,0,sizeof(t_),0,NULL,NULL }
247 
248 #define REDA_DEFINE_EMPTY_SEQUENCE_INITIALIZER \
249 { NULL,0,0,0,0,NULL,NULL }
250 
251 struct REDA_Sequence;
252 
253 /*ci
254  *\brief Internal flag set when sequence is using a loaned buffer.
255  */
256 #define REDA_SEQUENCE_FLAG_LOAN 0x01
257 
258 /*ci
259  *\brief Internal flag set when the sequencebuffer contains pointers to elements
260  */
261 #define REDA_SEQUENCE_FLAG_DISCONTIGUOUS 0x02
262 
263 /*ci
264  * \brief Initialize a sequence
265  *
266  * \details
267  *
268  * Initializes a sequence structure based on the element size.
269  * \return RTI_TRUE on success, RTI_FALSE on failure
270  *
271  * \param[in] self Sequence structure to initialize
272  *
273  * \param[in] element_size Size in bytes of the sequence structure
274  *
275  * \sa REDA_Sequence_finalize
276  */
277 MUST_CHECK_RETURN REDADllExport RTI_BOOL
278 REDA_Sequence_initialize(struct REDA_Sequence *self, RTI_INT32 element_size);
279 
280 /*ci
281  * \brief Finalize a sequence
282  *
283  * \details
284  *
285  * Finalize a sequence structure based
286  *
287  * \return RTI_TRUE on success, RTI_FALSE on failure
288  *
289  * \param[in] self Sequence structure to finalize
290  *
291  * \sa REDA_Sequence_initialize
292  */
293 SHOULD_CHECK_RETURN REDADllExport RTI_BOOL
294 REDA_Sequence_finalize(struct REDA_Sequence *self);
295 
296 /*ci
297  * \brief Get the current maximum of elements the sequence can store
298  *
299  * \details
300  *
301  * Return the current maximum number of elements a sequence can hold. The
302  * caller must ensure that self is not NULL.
303  *
304  * \param[in] self Sequence to return the maximum number of elements for
305  *
306  * \return maximum number of elements the sequence can hold.
307  *
308  * \sa REDA_Sequence_set_maximum
309  */
310 REDADllExport RTI_INT32
311 REDA_Sequence_get_maximum(const struct REDA_Sequence *self);
312 
313 /*ci
314  * \brief Set the current maximum of elements the sequence can store
315  *
316  * \details
317  *
318  * Set maximum number of elements a sequence can hold. The caller must
319  * ensure that self is not NULL. If new_max is larger than the current
320  * max additional memory is allocated if possible. If new_max is less
321  * than the current maximum memory may be freed.
322  *
323  * \param[in] self Sequence to change
324  * \param[in] new_max The new maximum number of elements the sequence can
325  * hold.
326  * \param[in] copy_content Whether the content of the sequence element should
327  * be copied or not. If copy_content is RTI_FALSE only
328  * the element array is resized, but the content of
329  * each element is not touched. If copy_content is
330  * RTI_TRUE then the content of each element is
331  * copied. This parameter is used by the typed wrapper
332  * functions to manage elements that manage their
333  * own memory, such as string sequences.
334  *
335  * \return RTI_TRUE on success, RTI_FALSE on failure.
336  *
337  * \sa REDA_Sequence_set_maximum
338  */
339 MUST_CHECK_RETURN REDADllExport RTI_BOOL
340 REDA_Sequence_set_maximum(struct REDA_Sequence *self, RTI_INT32 new_max,
341  RTI_BOOL copy_content);
342 
343 /*ci
344  * \brief Get the current number of elements in the sequence
345  *
346  * \details
347  *
348  * Return the current number of elements in the sequence.
349  *
350  * \param[in] self Sequence to return the current number of elements for
351  *
352  * \return Number of elements in the sequence.
353  *
354  * \sa REDA_Sequence_set_length
355  */
356 REDADllExport RTI_INT32
357 REDA_Sequence_get_length(const struct REDA_Sequence *self);
358 
359 /*ci
360  * \brief Set the current number of elements in the sequence
361  *
362  * \details
363  *
364  * Set the current number of elements in the sequence. Note that this function
365  * does not expand the sequence, rather it changes how many of the currently
366  * maximum number of elements are valid. Thus it is illegal to specify
367  * a new_length > get_maximum(self)
368  *
369  * \param[in] self Sequence to set the current number of elements for
370  * \param[in] new_length The number of elements in the sequence
371  *
372  * \return RTI_TRUE if the length was successfully changed, RTI_FALSE otherwise.
373  *
374  * \sa REDA_Sequence_get_length
375  */
376 MUST_CHECK_RETURN REDADllExport RTI_BOOL
377 REDA_Sequence_set_length(struct REDA_Sequence *self, RTI_INT32 new_length);
378 
379 /*ci
380  * \brief Return the underlying buffer holding sequence elements
381  *
382  * \details
383  *
384  * This function returns the underlying buffer holding up to max elements.
385  * It is guaranteed that the buffer is a contiguous memory area of at least
386  * element_size * maximum bytes.
387  *
388  * \param[in] self Sequence to get the current buffer for
389  *
390  * \return Current buffer or NULL if the sequence is not initialized.
391  *
392  * \sa REDA_Sequence_set_buffer
393  */
394 MUST_CHECK_RETURN REDADllExport void*
395 REDA_Sequence_get_buffer(const struct REDA_Sequence *self);
396 
397 /*ci
398  * \brief Set the underlying buffer holding sequence elements
399  *
400  * \details
401  *
402  * This function sets the underlying buffer holding up to max elements.
403  * It is guaranteed that the buffer is a contiguous memory area of at least
404  * element_size * maximum bytes.
405  *
406  * \param[in] self Sequence to set the current buffer for
407  *
408  * \param[in] buffer Buffer with sequence elements
409  *
410  * \return Current buffer or NULL if the sequence is not initialized.
411  *
412  * \sa REDA_Sequence_set_buffer
413  */
414 MUST_CHECK_RETURN REDADllExport RTI_BOOL
415 REDA_Sequence_set_buffer(struct REDA_Sequence *self, void *buffer);
416 
417 /*ci
418  * \brief Return a pointer to an element in the vector
419  *
420  * \details
421  *
422  * This function returns a pointer (reference) to an element in the vector
423  * given an index. The indexing is 0-based. If an index higher than the current
424  * length is specified NULL is returned.
425  *
426  * \param[in] self Sequence to return the element from
427  * \param[in] index Which element to return
428  *
429  * \return A reference to element index is returned, or NULL if the index
430  * is not within the current length.
431  */
432 MUST_CHECK_RETURN REDADllExport void*
433 REDA_Sequence_get_reference(const struct REDA_Sequence *self,RTI_INT32 index);
434 
435 /*ci
436  * \brief Copy the content of one sequence to another
437  *
438  * \details
439  *
440  * This function copies the content of the source sequence to the destination
441  * sequence, expanding the destination sequence if needed. The length of the
442  * destination will be equal to the source after the successful copying.
443  * it is not guaranteed that the maximum length of the two sequences are equal,
444  * only that the destination sequence is at least as large as the source
445  * sequence.
446  *
447  * \param[in] self Sequence to copy to
448  * \param[in] src Sequence to copy from
449  * \param[in] copy_content Whether the content of the sequence element should
450  * be copied or not. If copy_content is RTI_FALSE only
451  * the element array is resized, but the content of
452  * each element is not touched. If copy_content is
453  * RTI_TRUE then the content of each element is
454  * copied. This parameter is used by the typed wrapper
455  * functions to manage elements that manage their
456  * own memory, such as string sequences.
457  *
458  * \return A reference to destination sequence is returned on success, otherwise
459  * NULL is returned.
460  */
461 MUST_CHECK_RETURN REDADllExport struct REDA_Sequence*
462 REDA_Sequence_copy(struct REDA_Sequence *self,
463  const struct REDA_Sequence *src,
464  RTI_BOOL copy_content);
465 
466 /*ci
467  * \brief Compare two sequences
468  *
469  * \details
470  *
471  * Compare two function for equality. Two sequences are considered to be equal
472  * if the sequences are of the same length and the content of each element
473  * in the same position is identical.
474  *
475  * \param[in] left Left side of the comparison
476  * \param[in] right Right side of the comparison
477  * \param[in] compare_content Whether the content of the sequence element should
478  * be compared or not. If compare_content is
479  * RTI_FALSE only the element array sizes are
480  * compared, but the content of
481  * each element is not compared. If compare_content
482  * is RTI_TRUE then the content of each element is
483  * compared. This parameter is used by the typed
484  * wrapper functions to manage elements that manage
485  * their own memory, such as string sequences.
486  *
487  * \return RTI_TRUE if the sequences are equal, RTI_FALSE otherwise.
488  */
489 REDADllExport RTI_BOOL
490 REDA_Sequence_is_equal(const struct REDA_Sequence *left,
491  const struct REDA_Sequence *right,
492  RTI_BOOL compare_content);
493 
494 /*ci
495  * \brief Loan an external, contiguous buffer to a sequence
496  *
497  * \details
498  *
499  * Typically a sequence manages its own memory. However, it is possible to
500  * loan the sequence a buffer of elements. When a sequence is loaning a
501  * buffer it is not allowed to resize it. The caller must first unloan the
502  * sequence and then loan the sequence a different buffer. In a contiguous
503  * buffer it is assumed that each element is contained in the buffer. It
504  * is not legal to loan a buffer to a sequence currently managing its own
505  * element buffer. In this case the sequence must first be finalized.
506  *
507  * \param[in] self Sequence to loan buffer to
508  * \param[in] buffer Buffer to loan
509  * \param[in] new_length The number of valid elements in the buffer
510  * \param[in] new_max The maximum number of elements the buffer can hold
511  *
512  * \return RTI_TRUE is returned if the loan is successful, RTI_FALSE otherwise
513  */
514 MUST_CHECK_RETURN REDADllExport RTI_BOOL
515 REDA_Sequence_loan_contiguous(struct REDA_Sequence *self, void *buffer,
516  RTI_INT32 new_length, RTI_INT32 new_max);
517 
518 /*ci
519  * \brief Loan an external, discontiguous buffer to a sequence
520  *
521  * \details
522  *
523  * Typically a sequence manages its own memory. However, it is possible to
524  * loan the sequence a buffer of elements. When a sequence is loaning a
525  * buffer it is not allowed to resize it. The caller must first unloan the
526  * sequence and then loan the sequence a different buffer. In a discontiguous
527  * buffer it is assumed that each element is a reference to the actual element
528  * contained in the buffer. It is not legal to loan a buffer to a sequence
529  * currently managing its own element buffer. In this case the sequence must
530  * first be finalized.
531  *
532  * \param[in] self Sequence to loan buffer to
533  * \param[in] buffer Buffer to loan
534  * \param[in] new_length The number of valid elements in the buffer
535  * \param[in] new_max The maximum number of elements the buffer can hold
536  *
537  * \return RTI_TRUE is returned if the loan is successful, RTI_FALSE otherwise
538  */
539 MUST_CHECK_RETURN REDADllExport RTI_BOOL
540 REDA_Sequence_loan_discontiguous(struct REDA_Sequence *self, void *buffer,
541  RTI_INT32 new_length, RTI_INT32 new_max);
542 /*ci
543  * \brief Remove a loan of an external buffer to a sequence
544  *
545  * \details
546  *
547  * Remove a previously loaned buffer from a sequence.
548  *
549  * \param[in] self Sequence to unloan the buffer from
550  *
551  * \return RTI_TRUE is returned if the unloan is successful, RTI_FALSE otherwise
552  *
553  * \sa \ref REDA_Sequence_loan_discontiguous, \ref REDA_Sequence_loan_contiguous
554  */
555 MUST_CHECK_RETURN REDADllExport RTI_BOOL
556 REDA_Sequence_unloan(struct REDA_Sequence *self);
557 
558 /*ci
559  * \brief Check if a sequence owns the current element buffer or not
560  *
561  * \details
562  *
563  * Check if a sequence owns the current element buffer or not
564  *
565  * \param[in] self Sequence to check ownership for
566  *
567  * \return RTI_TRUE if the sequence owns the buffer, RTI_FALSE if not
568  *
569  * \sa \ref REDA_Sequence_loan_discontiguous, \ref REDA_Sequence_loan_contiguous
570  */
571 REDADllExport RTI_BOOL
572 REDA_Sequence_has_ownership(const struct REDA_Sequence *self);
573 
574 /*ci
575  * \brief Check if a sequence uses a contiguous or discontinuous buffer
576  *
577  * \details
578  *
579  * Check if a sequence uses a contiguous or discontinuous buffer
580  *
581  * \param[in] self Sequence to check ownership for
582  *
583  * \return RTI_TRUE if the sequence is contiguous, RTI_FALSE if not
584  *
585  * \sa \ref REDA_Sequence_loan_discontiguous
586  */
587 REDADllExport RTI_BOOL
588 REDA_Sequence_has_discontiguous_buffer(const struct REDA_Sequence *self);
589 
590 /*ci
591  * \brief Set a token on a sequence
592  *
593  * \details
594  * A token is an opaque pointer stored in the sequence. It has no meaning
595  * to the sequence and is not considered part of the content.
596  *
597  * \param[in] self Sequence to get the current buffer for
598  * \param[in] token1 The first token to associate with the sequence
599  * \param[in] token2 The second token to associate with the sequence
600  *
601  * \sa REDA_Sequence_get_token
602  */
603 REDADllExport void
604 REDA_Sequence_set_token(struct REDA_Sequence *self,void *token1,void *token2);
605 
606 /*ci
607  * \brief Get the token from a sequence
608  *
609  * \details
610  * A token is an opaque pointer stored in the sequence. It has no meaning
611  * to the sequence and is not considered part of the content.
612  *
613  * \param[in] self Sequence to get the current buffer for
614  * \param[out] token1 The first token associated with the sequence
615  * \param[out] token2 The second token associated with the sequence
616  *
617  * \sa REDA_Sequence_set_token
618  */
619 REDADllExport void
620 REDA_Sequence_get_token(const struct REDA_Sequence *self,void **token1,void **token2);
621 
622 #ifdef __cplusplus
623 } /* extern "C" */
624 #endif
625 
626 #endif /* reda_sequence_h */
627 
628 /*ci @} */
RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc