RTI Connext DDS Micro  Version 2.4.7
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
dds_c_wh_plugin.h
Go to the documentation of this file.
1 /*
2  * FILE: dds_c_wh_plugin.h - DDS writer history interface
3  *
4  * (c) Copyright, Real-Time Innovations, 2011-2015.
5  *
6  * All rights reserved.
7  *
8  * No duplications, whole or partial, manual or electronic, may be made
9  * without express written permission. Any such copies, or
10  * revisions thereof, must display this notice unaltered.
11  * This code contains trade secrets of Real-Time Innovations, Inc.
12  *
13  * Modification History
14  * --------------------
15  * 04nov2015,tk MICRO-1505 Reduce memory footprint
16  * 24feb2014,tk MICRO-714: Updated for improved writer history API.
17  * 03feb2014,eh MICRO-714: acknack_sample, on_sample_removed
18  * 16aug2011,tk Written
19  */
20 /*ce
21  * \file
22  * \brief DDS writer history interface
23  */
24 /*ci \defgroup DDSHistoryModule DDS History module
25  * \ingroup DDSCModule
26  */
27 /*ci \defgroup DDSWriterHistoryModule DDS Writer History module
28  * \ingroup DDSHistoryModule
29  */
30 /*ci \addtogroup DDSWriterHistoryModule
31  * @{
32  */
33 #ifndef dds_c_wh_plugin_h
34 #define dds_c_wh_plugin_h
35 
36 #ifndef rt_rt_h
37 #include "rt/rt_rt.h"
38 #endif
39 #ifndef dds_c_topic_h
40 #include "dds_c/dds_c_topic.h"
41 #endif
42 #ifndef dds_c_dll_h
43 #include "dds_c/dds_c_dll.h"
44 #endif
45 #ifndef dds_c_discovery_h
46 #include "dds_c/dds_c_discovery.h"
47 #endif
48 #ifndef dds_c_type_h
49 #include "dds_c/dds_c_type.h"
50 #endif
51 
52 #ifdef __cplusplus
53 extern "C"
54 {
55 #endif
56 
57 /*ce
58  * \brief Default writer history plug-in name
59  */
60 DDSCDllVariable extern const char* const DDSHST_WRITER_DEFAULT_HISTORY_NAME;
61 
62 /*ci
63  * \brief Enumeration of supported writer history events
64  */
65 typedef enum
66 {
67  /*ci
68  * \brief The deadline timer expired, check deadlines
69  */
70  DDSHST_WRITEREVENT_KIND_DEADLINE_EXPIRED = 1,
71 
72  /*ci
73  * \brief A late joiner is requesting historical data
74  */
75  DDSHST_WRITEREVENT_KIND_HISTORICAL_DATA_REQUESTED
76 } DDSHST_WriterEventKind_T;
77 
78 /*ci
79  * \brief A writer history event that can be posted to the cache
80  */
81 struct DDSHST_WriterEvent
82 {
83  /*ci
84  * \brief The event type
85  */
86  DDSHST_WriterEventKind_T kind;
87 };
88 
89 /*ci
90  * \brief Base-class for writer history cache
91  */
92 struct DDSHST_Writer
93 {
94  struct RT_Component _parent;
95 };
96 
97 typedef struct DDSHST_Writer DDSHST_Writer_T;
98 
99 struct DDSHST_WriterSampleEntry;
100 
101 /*ci
102  * \brief Implementation independent reference to a sample in the
103  * writer history cache
104  */
105 typedef struct DDSHST_WriterSampleEntry* DDSHST_WriterSampleEntryRef_T;
106 
107 /*ci
108  * \brief Implementation independent writer cache sample
109  */
110 typedef struct DDSHST_WriterSample
111 {
112  /*ci
113  * \brief Reference to the corresponding entry in the implementation specific
114  * cache
115  */
116  DDSHST_WriterSampleEntryRef_T _ref;
117 } DDSHST_WriterSample_T;
118 
119 /*ci
120  * \brief The current state of the writer cache
121  */
122 struct DDSHST_WriterState
123 {
124  /*ci
125  * \brief The lowest SN available, across all instances
126  */
127  struct REDA_SequenceNumber low_sn;
128 
129  /*ci
130  * \brief The highest SN available, across all instances
131  */
132  struct REDA_SequenceNumber high_sn;
133 
134  /*ci
135  * \brief The lowest historical SN available, across all instances
136  */
137  struct REDA_SequenceNumber history_low_sn;
138 
139  /*ci
140  * \brief The highest historical SN available, across all instances
141  */
142  struct REDA_SequenceNumber history_high_sn;
143 };
144 
145 /*ci
146  * \brief Base-class properties for the DDS writer history cache
147  */
148 struct DDSHST_WriterProperty
149 {
150  /*ci
151  * \brief Inherit from a component
152  */
153  struct RT_ComponentProperty _parent;
154 
155  /*ci
156  * \brief Pointer to the qos policy for the DDS writer that uses the history
157  * cache
158  */
159  struct DDS_DataWriterQos *qos;
160 };
161 
162 /*ci
163  * \brief Constant to initialize \ref DDSHST_WriterProperty
164  */
165 #define DDSHST_WriterProperty_INITIALIZER \
166 {\
167  RT_ComponentProperty_INITIALIZER,\
168  NULL\
169 }
170 
171 /*ci
172  * \brief Enumeration of the different reasons a sample was removed from the
173  * writer cache
174  */
175 typedef enum
176 {
177  /*ci
178  * \brief Normal removal, the cache no longer needs this sample
179  */
180  DDSHST_WRITER_SAMPLE_REMOVED_NORMAL,
181 
182  /*ci
183  * \brief A sample was forcefully removed to make space, 1 or reliable readers
184  * did not receive it
185  */
186  DDSHST_WRITER_SAMPLE_REMOVED_UNACKED,
187 
188  /*ci
189  * \brief The sample was removed because the key was unregistered
190  */
191  DDSHST_WRITER_SAMPLE_REMOVED_KEY_UNREGISTERED,
192 
193  /*ci
194  * \brief The sample was removed because the key was disposed
195  */
196  DDSHST_WRITER_SAMPLE_REMOVED_KEY_DISPOSED,
197 
198  /*ci
199  * \brief The sample was removed because the resource limit for samples
200  * per instance was reached and KEEP_LAST is in effect
201  */
202  DDSHST_WRITER_SAMPLE_REMOVED_MAX_SAMPLES_PER_INSTANCE
203 } DDSHST_WriterSampleRemovedKind_T;
204 
205 /*ci
206  * \brief Enumeration of the different reasons a key was removed from the
207  * writer cache
208  */
209 typedef enum
210 {
211  /*ci
212  * \brief Normal removal, the key is no longer needed
213  */
214  DDSHST_WRITER_KEY_REMOVED_NORMAL,
215 
216  /*ci
217  * \brief The key was removed due to being unregistered
218  */
219  DDSHST_WRITER_KEY_REMOVED_UNREGISTERED,
220 
221  /*ci
222  * \brief The key was removed due to being disposed of
223  */
224  DDSHST_WRITER_KEY_REMOVED_DISPOSED
225 } DDSHST_WriterKeyRemovedKind_T;
226 
227 /*ci
228  * \brief Enumeration of the different types of queue entries
229  */
230 typedef enum
231 {
232  /*ci
233  * \brief Normal user data entry
234  */
235  DDSHST_WRITER_ENTRY_NORMAL,
236 
237  /*ci
238  * \brief The sample is the result of an unregister operation
239  */
240  DDSHST_WRITER_ENTRY_UNREGISTER,
241 
242  /*ci
243  * \brief The sample is the result of a dispose operation
244  */
245  DDSHST_WRITER_ENTRY_DISPOSE,
246 
247  /*ci
248  * \brief The sample is the result of a unregister and dispose operation
249  */
250  DDSHST_WRITER_ENTRY_UNREGISTER_DISPOSE
251 } DDSHST_WriterEntryKind_T;
252 
253 /*ci
254  * \def DDSHST_WRITER_ACKCOUNT_ANY
255  * \brief Constant to indicate that the number of ACKNACKs for a sample is
256  * not relevant
257  */
258 #define DDSHST_WRITER_ACKCOUNT_ANY (0)
259 
260 /*ci
261  * \brief Definition of the \ref DDSHST_WriterListener on_sample_removed callback
262  *
263  * \details
264  * When the history cache removes a sample it calls this listener if it is
265  * installed.
266  *
267  * \param[in] listener_data Opaque pointer to listener data
268  * \param[in] key The key the sample belonged too
269  * \param[in] sample The sample being removed
270  * \param[in] sn The sequence number of the removed sample
271  * \param[in] kind The reason the sample is removed
272  * \param[in] ack_count The current number of acknowledgment on the sample
273  */
274 typedef void
275 (*DDSHST_WriterListener_OnSampleRemovedFunc)(
276  void *listener_data,
278  struct DDSHST_WriterSample *sample,
279  struct REDA_SequenceNumber *sn,
280  DDSHST_WriterSampleRemovedKind_T kind,
281  DDS_Long ack_count);
282 /*ci
283  * \brief Definition of the \ref DDSHST_WriterListener on_deadline_missed callback
284  *
285  * \details
286  * When an instance is not being updated according to the deadline the cache
287  * calls this listener if it is installed.
288  *
289  * \param[in] listener_data Opaque pointer to listener data
290  * \param[in] key The key that missed its deadline
291  */
292 typedef void
293 (*DDSHST_WriterListener_OnDeadlineMissedFunc)(void *listener_data,
294  DDS_InstanceHandle_t *key);
295 
296 /*ci
297  * \brief Definition of the \ref DDSHST_WriterListener on_key_removed callback
298  *
299  * \details
300  * When the history cache removes a key it calls this listener if it is
301  * installed.
302  *
303  * \param[in] listener_data Opaque pointer to listener data
304  * \param[in] key The key being removed
305  * \param[in] kind The reason for removing the key
306  */
307 typedef void
308 (*DDSHST_WriterListener_OnKeyRemovedFunc)(void *listener_data,
310  DDSHST_WriterKeyRemovedKind_T kind);
311 
312 /*ci
313  * \brief Base-class for DDS Writer history listener
314  */
315 struct DDSHST_WriterListener
316 {
317  /*ci
318  * \brief Inherit from parent class
319  */
320  struct RT_ComponentListener _parent;
321 
322  /*ci
323  * \brief Called when the cache removed a sample
324  */
325  DDSHST_WriterListener_OnSampleRemovedFunc on_sample_removed;
326 
327  /*ci
328  * \brief Called when the cache removed a key
329  */
330  DDSHST_WriterListener_OnKeyRemovedFunc on_key_removed;
331 
332  /*ci
333  * \brief Called when the cache detected deadline missed on an instance
334  */
335  DDSHST_WriterListener_OnDeadlineMissedFunc on_deadline_missed;
336 
337  /*ci
338  * \brief Opaque listener data passed back to listener functions
339  */
340  void *listener_data;
341 };
342 
343 /*ci
344  * \brief Constant to initialize \ref DDSHST_WriterListener
345  */
346 #define DDSHST_WriterListener_INITIALIZE {\
347  RT_ComponentListener_INITIALIZER,\
348  NULL,\
349  NULL,\
350  NULL,\
351  NULL\
352 }
353 
354 /* ------------------------------ Life-cycle -------------------------------- */
355 /*ci
356  * \brief Definition of \ref RT_ComponentFactory delete_component method
357  *
358  * \param[in] self The writer history instance to delete
359  *
360  * \sa \ref RT_ComponentFactoryI
361  */
362 typedef void
363 (*DDSHST_Writer_deleteFunc)(struct DDSHST_Writer *self);
364 
365 /*ci
366  * \brief Definition of \ref RT_ComponentFactory create_component method
367  *
368  * \param[in] property The component property
369  * \param[in] listener The component listener
370  *
371  * \return A reference to a new writer cache on success, NULL otherwise
372  *
373  * \sa \ref RT_ComponentFactoryI
374  */
375 FUNCTION_MUST_TYPEDEF(
376 struct DDSHST_Writer*
377 (*DDSHST_Writer_createFunc) (const struct DDSHST_WriterProperty* const property,
378  const struct DDSHST_WriterListener* const listener)
379 )
380 
381 /* ------------------------------- Methods ---------------------------------- */
382 /*ci
383  * \brief Definition of \ref DDSHST_WriterI get_entry method
384  *
385  * \param[in] self The writer cache to get an entry from
386  * \param[in] key The key to get an entry for
387  * \param[in] kind The kind of entry (dispose, unregister, normal etc.)
388  * \param[in] assert_key If TRUE, assert the key if it does not already exist.
389  * Otherwise return NULL if the key does not exist.
390  *
391  * \return A reference to new entry if there is space, NULL otherwise
392  *
393  * \sa \ref DDSHST_Writer_get_entry, \ref DDSHST_WriterI
394  */
395 FUNCTION_MUST_TYPEDEF(
396 DDSHST_WriterSampleEntryRef_T
397 (*DDSHST_Writer_get_entryFunc)(struct DDSHST_Writer *self,
398  const DDS_InstanceHandle_t *const key,
399  DDSHST_WriterEntryKind_T kind, RTI_BOOL assert_key);
400 )
401 
402 /*ci
403  * \brief Definition of \ref DDSHST_WriterI return_entry method
404  *
405  * \details
406  * Return an entry to the cache
407  *
408  * \param[in] self The history cache
409  * \param[in] entry A reference to the entry to return
410  *
411  * \sa \ref DDSHST_Writer_return_entry, \ref DDSHST_WriterI
412  */
413 typedef void
414 (*DDSHST_Writer_return_entryFunc)(struct DDSHST_Writer *self,
415  DDSHST_WriterSampleEntryRef_T const entry);
416 
417 /*ci
418  * \brief Definition of \ref DDSHST_WriterI commit_entry method
419  *
420  * \details
421  * Method to commit a a sample to the cache
422  *
423  * \param[in] self The history cache
424  * \param[out] sample The requested sample if found, NULL otherwise
425  * \param[in] sn The requested SN
426  * \param[out] sn_ge The first available SN
427  * \param[in] h Whether only historical samples are relevant
428  *
429  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref DDSHST_ReturnCode_T
430  * on failure
431  *
432  * \sa \ref DDSHST_Writer_commit_entry, \ref DDSHST_WriterI
433  */
434 FUNCTION_MUST_TYPEDEF(
435 DDSHST_ReturnCode_T
436 (*DDSHST_Writer_commit_entryFunc)(struct DDSHST_Writer * self,
437  DDSHST_WriterSampleEntryRef_T entry,
438  DDSHST_WriterSample_T *const sample,
439  const struct REDA_SequenceNumber *const sn,
440  DDS_Long ack_count)
441 )
442 
443 /*ci
444  * \brief Definition of \ref DDSHST_WriterI request_sample method
445  *
446  * \details
447  * Method to request a sample from the cache
448  *
449  * \param[in] self The history cache
450  * \param[out] sample The requested sample if found, NULL otherwise
451  * \param[in] sn The requested SN
452  * \param[out] sn_ge The first available SN
453  * \param[in] h Whether only historical samples are relevant
454  *
455  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref DDSHST_ReturnCode_T
456  * on failure
457  *
458  * \sa \ref DDSHST_Writer_request_sample, \ref DDSHST_WriterI
459  */
460 FUNCTION_MUST_TYPEDEF(
461 DDSHST_ReturnCode_T
462 (*DDSHST_Writer_request_sampleFunc)(struct DDSHST_Writer *self,
463  struct DDSHST_WriterSample **sample,
464  const struct REDA_SequenceNumber *const req_sn,
465  struct REDA_SequenceNumber *const sn_ge,
466  DDS_Boolean historical_only)
467 )
468 
469 /*ci
470  * \brief Definition of \ref DDSHST_WriterI acknack_sample method
471  *
472  * \details
473  * Method to ACK or NACK a sample in the queue
474  *
475  * \param[in] self The writer cache
476  * \param[in] sn The SN to ACKNACK
477  * \param[in] nack Whether this is a NACK (DDS_BOOLEAN_TRUE) or ACK
478  * (DDS_BOOLEAN_FALSE)
479  *
480  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref
481  * DDSHST_ReturnCode_T on failure
482  *
483  * \sa \ref DDSHST_Writer_acknack_sample, \ref DDSHST_WriterI
484  */
485 FUNCTION_MUST_TYPEDEF(
486 DDSHST_ReturnCode_T
487 (*DDSHST_Writer_acknack_sampleFunc)(struct DDSHST_Writer *self,
488  const struct REDA_SequenceNumber *const sn,
489  DDS_Boolean nack)
490 )
491 
492 /*ci
493  * \brief Definition of \ref DDSHST_WriterI register_key method
494  *
495  * \details
496  * Method to add a key to the cache if there is space
497  *
498  * \param[in] self The history cache
499  * \param[in] key The key to add to the cache
500  *
501  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref
502  * DDSHST_ReturnCode_T on failure
503  *
504  * \sa \ref DDSHST_Writer_register_key, \ref DDSHST_WriterI
505  */
506 FUNCTION_MUST_TYPEDEF(
507 DDSHST_ReturnCode_T
508 (*DDSHST_Writer_register_keyFunc)(struct DDSHST_Writer *self,
509  const DDS_InstanceHandle_t *const key)
510 )
511 
512 /*ci
513  * \brief Definition of \ref DDSHST_WriterI get_state method
514  *
515  * \details
516  * Return the current state of the writer cache.
517  *
518  * \param[in] self The history cache
519  *
520  * \return Pointer to the structure containing the state
521  *
522  * \sa \ref DDSHST_Writer_get_state, \ref DDSHST_WriterI
523  */
524 FUNCTION_MUST_TYPEDEF(
525 struct DDSHST_WriterState*
526 (*DDSHST_Writer_get_stateFunc)(struct DDSHST_Writer *self)
527 )
528 
529 /*ci
530  * \brief Definition of \ref DDSHST_WriterI post_event method
531  *
532  * \details
533  * Handle possible events posted to the cache by the user.
534  *
535  * \param[in] self The history cache
536  * \param[in] event The event
537  * \param[in] now The time of the event
538  *
539  * \sa \ref DDSHST_Writer_post_event, \ref DDSHST_WriterI
540  */
541 typedef void
542 (*DDSHST_Writer_post_eventFunc)(struct DDSHST_Writer *self,
543  struct DDSHST_WriterEvent *event,
544  struct OSAPI_NtpTime *now);
545 
546 /*ci
547  * \brief Definition of the DDS Writer History interface
548  */
549 struct DDSHST_WriterI
550 {
551  /*ci
552  * \brief Base-class interface
553  */
554  struct RT_ComponentI _parent;
555 
556  /*ci
557  * \brief Method to get an entry from the cache, if available
558  */
559  DDSHST_Writer_get_entryFunc get_entry;
560 
561  /*ci
562  * \brief Method to return an entry back to the cache if not needed
563  */
564  DDSHST_Writer_return_entryFunc return_entry;
565 
566  /*ci
567  * \brief Method to commit an entry to the cache
568  */
569  DDSHST_Writer_commit_entryFunc commit_entry;
570 
571  /*ci
572  * \brief Method to request an entry from the cache
573  */
574  DDSHST_Writer_request_sampleFunc request_sample;
575 
576  /*ci
577  * \brief Method to ACK or NACK an entry in the cache
578  */
579  DDSHST_Writer_acknack_sampleFunc acknack_sample;
580 
581  /*ci
582  * \brief Method to register a key in the cache, if possible
583  */
584  DDSHST_Writer_register_keyFunc register_key;
585 
586  /*ci
587  * \brief Method to get the current state of the writer cache
588  */
589  DDSHST_Writer_get_stateFunc get_state;
590 
591  /*ci
592  * \brief Method to post an event to the writer cache
593  */
594  DDSHST_Writer_post_eventFunc post_event;
595 };
596 
597 /*ci
598  * \brief Wrapper to call of the DDSHST_WriterFactory->create_component
599  *
600  * \param[in] f_ The writer history factory
601  * \param[in] p_ The property
602  * \param[in] l_ The listener
603  *
604  * \return A reference to new writer cache on success, NULL otherwise
605  */
606 #define DDSHST_WriterFactory_create_component(f_,p_,l_) \
607  (struct DDSHST_Writer*)((f_)->intf)->create_component(f_,p_,l_)
608 
609 /*ci
610  * \brief Wrapper to call of the DDSHST_WriterFactory->delete_component
611  *
612  * \param[in] f_ The writer history factory
613  * \param[in] c_ The cache to delete
614  */
615 #define DDSHST_WriterFactory_delete_component(f_,c_) \
616  ((f_)->intf)->delete_component(f_,(RT_Component_T*)(c_))
617 
618 /*ci
619  * \brief Wrapper to call of the DDSHST_WriterI->get_entry
620  *
621  * \param[in] self_ The writer cache to get an entry from
622  * \param[in] key_ The key to get an entry for
623  * \param[in] kind_ The kind of entry (dispose, unregister, normal etc.)
624  * \param[in] assert_key_ If TRUE, assert the key if it does not already exist.
625  * Otherwise return NULL if the key does not exist.
626  *
627  * \return A reference to new entry if there is space, NULL otherwise
628  */
629 #define DDSHST_Writer_get_entry(self_,key_,kind_,assert_key_) \
630  ((struct DDSHST_WriterI*)(\
631  (self_)->_parent._intf))->get_entry(self_,key_,kind_,assert_key_)
632 
633 /*ci
634  * \brief Wrapper to call of the DDSHST_WriterI->return_entry function
635  *
636  * \details
637  * Return an entry to cache, it is unused
638  *
639  * \param[in] self_ The history cache
640  * \param[in] entry_ A reference to the entry to return
641  */
642 #define DDSHST_Writer_return_entry(self_,entry_) \
643  ((struct DDSHST_WriterI*)(\
644  (self_)->_parent._intf))->return_entry(self_,entry_)
645 
646 /*ci
647  * \brief Wrapper to call of the DDSHST_WriterI->commit_entry function
648  *
649  * \details
650  * Commit an entry to the writer cache, updating the state of the cache.
651  * The ack_count_ is the expected number of acknowledgments before the sample
652  * SN can be marked as ACK'ed
653  *
654  * \param[in] self_ The writer cache
655  * \param[in] entry_ A reference to a previously allocated entry
656  * \param[in] sample_ The entries's payload (opaque to the cache)
657  * \param[in] sn_ The sequence number of the entry
658  * \param[in] ack_count_ The expected number of acknowledgment for this sample
659  * based on the number of reliable peers
660  *
661  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref
662  * DDSHST_ReturnCode_T on failure
663  */
664 #define DDSHST_Writer_commit_entry(self_,entry_,sample_,sn_,ack_count_) \
665  ((struct DDSHST_WriterI*)(\
666  (self_)->_parent._intf))->commit_entry(self_,entry_,\
667  sample_,sn_,ack_count_)
668 
669 /*ci
670  * \brief Wrapper to call of the DDSHST_WriterI->request_sample function
671  *
672  * \details
673  * Return a reference to a history sample based on the requested SN.
674  * A sample that is requested is automatically considered
675  * unacknowledged and will not be removed from the queue unless forced by an
676  * ACKNACK. Thus, a sample which was ACK'ed may go back to UNACK'ed state. A
677  * request does not change the history.
678  * \p
679  * The cache can search in all samples or only the historical samples
680  * based on the historical_only flag. This function always returns the next
681  * available SN if the requested cannot be found. If the requested SN is found
682  * the first available is set to the requested SN.
683  *
684  * \param[in] self_ The history cache
685  * \param[out] sample_ The requested sample if found, NULL otherwise
686  * \param[in] sn_ The requested SN
687  * \param[out] sn_ge_ The first available SN
688  * \param[in] h_ Whether only historical samples are relevant
689  *
690  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref DDSHST_ReturnCode_T
691  * on failure
692  */
693 #define DDSHST_Writer_request_sample(self_,sample_,sn_,sn_ge_,h_) \
694  ((struct DDSHST_WriterI*)(\
695  (self_)->_parent._intf))->request_sample(self_,sample_,sn_,sn_ge_,h_)
696 
697 /*ci
698  * \brief Wrapper to call of the DDSHST_WriterI->acknack_sample function
699  *
700  * \details
701  * When a SN is ACK'ed it tells the queue that as far as the external
702  * view is concerned that sample is no longer needed. However, the queue
703  * can be configured to keep samples to delivery to late joiners.
704  *
705  * There are 3 types of sample that can be ACK'ed:
706  * - normal sample: This is regular user-data and does not change the key state.
707  * Normal data samples that are ACK'ed are usually returned to
708  * the buffer-pool or kept around for history.
709  * - unregister sample: An ACK'ed unregister sample means that everybody has
710  * acknowledged the unregistration from this queue. If
711  * there are no more samples in the queue then the
712  * key will be reclaimed. If the key is not empty then
713  * the key resources are not reclaimed.
714  * - dispose sample: An ACK'ed dispose sample means that everybody has
715  * acknowledged the disposal from this queue. However,
716  * disposed keys cannot be reclaimed.
717  *
718  * If NACK is DDS_BOOLEAN true the sample was not delivered to all, but
719  * it can be removed as no further attempts to deliver it will be made.
720  *
721  * \param[in] self_ The writer cache
722  * \param[in] sn_ The SN to ACKNACK
723  * \param[in] nack_ Whether this is a NACK (DDS_BOOLEAN_TRUE) or ACK
724  * (DDS_BOOLEAN_FALSE)
725  *
726  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref
727  * DDSHST_ReturnCode_T on failure
728  */
729 #define DDSHST_Writer_acknack_sample(self_,sn_,nack_) \
730 ((struct DDSHST_WriterI*)(\
731  (self_)->_parent._intf))->acknack_sample(self_,sn_,nack_)
732 
733 /*ci
734  * \brief Wrapper to call of the DDSHST_WriterI->register_key function
735  *
736  * \details
737  * Add a key to the cache if there is space.
738  *
739  * \param[in] self_ The history cache
740  * \param[in] key_ The key to add to the cache
741  *
742  * \return DDSHST_RETCODE_SUCCESS on success, one of \ref
743  * DDSHST_ReturnCode_T on failure
744  */
745 #define DDSHST_Writer_register_key(self_,key_) \
746  ((struct DDSHST_WriterI*)(\
747  (self_)->_parent._intf))->register_key(self_,key_)
748 
749 /*ci
750  * \brief Wrapper to call the \ref DDSHST_WriterI::get_state function
751  *
752  * \details
753  * Return the current state of the writer cache. This information
754  * is used to determine which sequence numbers are relevant when
755  * the durability is in effect.
756  *
757  * \param[in] self_ The history cache
758  *
759  * \return Pointer to the structure containing the state
760  */
761 #define DDSHST_Writer_get_state(self_) \
762  ((struct DDSHST_WriterI*)(\
763  (self_)->_parent._intf))->get_state(self_)
764 
765 /*ci
766  * \brief Wrapper to call the \ref DDSHST_WriterI ->post_event function
767  *
768  * \details
769  * Handle possible events posted to the cache by the user. The events
770  * handled are deadline tests (the deadline timer is not owned by the cache)
771  * and update expected ACKNACKs when a reliable late joiner as added. Note
772  * that the cache does not keep track of peers, only how many there are.
773  *
774  * \param[in] self_ The history cache
775  * \param[in] event_ The event
776  * \param[in] time_ The time of the event
777  */
778 #define DDSHST_Writer_post_event(self_,event_,time_) \
779  ((struct DDSHST_WriterI*)(\
780  (self_)->_parent._intf))->post_event(self_,event_,time_)
781 
782 #ifdef __cplusplus
783 } /* extern "C" */
784 #endif
785 
786 
787 #endif /* dds_c_wh_plugin_h */
788 
789 /*ci @} */

RTI Connext DDS Micro Version 2.4.7 Copyright © Fri Feb 26 2016 Real-Time Innovations, Inc