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

RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc