RTI Connext DDS Micro  Version 2.4.8
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
dds_c_rh_plugin.h
Go to the documentation of this file.
1 /*
2  * FILE: dds_c_rh_plugin.h - DDS reader 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  * 19may2015,as MICRO-1193 Refactoring of Sequence API levels
17  * 08oct2014,tk MICRO-919 Added SampleLostReason to SampleLost status
18  * 16aug2011,tk Written
19  */
20 /*ce
21  * \file
22  * \brief DDS reader history interface
23  */
24 /*ci \defgroup DDSHistoryModule DDS History module
25  * \ingroup DDSCModule
26  */
27 /*ci \defgroup DDSReaderHistoryModule DDS Reader History module
28  * \ingroup DDSHistoryModule
29  */
30 /*ci \addtogroup DDSReaderHistoryModule
31  * @{
32  */
33 #ifndef dds_c_rh_plugin_h
34 #define dds_c_rh_plugin_h
35 
36 
37 #ifndef dds_c_dll_h
38 #include "dds_c/dds_c_dll.h"
39 #endif
40 #ifndef dds_c_discovery_h
41 #include "dds_c/dds_c_discovery.h"
42 #endif
43 
44 #ifdef __cplusplus
45 extern "C"
46 {
47 #endif
48 
49 /*ce
50  * \brief Default reader history plug-in name
51  */
52 DDSCDllVariable extern const char* const DDSHST_READER_DEFAULT_HISTORY_NAME;
53 
54 /*ci
55  * \brief Enumeration of supported reader history events
56  */
57 typedef enum
58 {
59  /*ci
60  * \brief Liveliness was lost on a remote writer
61  */
62  DDSHST_READEREVENT_KIND_LIVELINESS_LOST = 1,
63 
64  /*ci
65  * \brief Liveliness was detected on a remote writer
66  */
67  DDSHST_READEREVENT_KIND_LIVELINESS_DETECTED,
68 
69  /*ci
70  * \brief A remote writer was deleted
71  */
72  DDSHST_READEREVENT_KIND_REMOTE_WRITER_DELETED,
73 
74  /*ci
75  * \brief The deadline timer expired, check deadlines
76  */
77  DDSHST_READEREVENT_KIND_DEADLINE_EXPIRED
78 } DDSHST_ReaderEventKind_T;
79 
80 /*ci
81  * \brief A reader history event that can be posted to the cache
82  */
83 struct DDSHST_ReaderEvent
84 {
85  /*ci
86  * \brief The event type
87  */
88  DDSHST_ReaderEventKind_T kind;
89 
90  /*ci
91  * \brief event data based on the kind
92  */
93  union
94  {
95  /*ci
96  * \brief Event data associated with liveliness loss/detection
97  */
98  struct
99  {
100  /*ci
101  * \brief Remote writer key liveliness changed on
102  */
103  DDS_InstanceHandle_t rw_guid;
104 
105  /*ci
106  * \brief The key for the instance that changed liveliness
107  */
108  DDS_InstanceHandle_t instance;
109  } liveliness;
110 
111  /*ci
112  * \brief Event data associated with remote writer deletion
113  */
114  struct
115  {
116  /*ci
117  * \brief The GUID of the deleteted remote writer
118  */
119  DDS_InstanceHandle_t rw_guid;
120  } rw_deleted;
121  } data;
122 };
123 
124 /*ci
125  * \brief Base-class for reader history cache
126  */
127 struct DDSHST_Reader
128 {
129  /*ci
130  * \brief Inherit from base-class
131  */
132  struct RT_Component _parent;
133 };
134 
135 typedef struct DDSHST_Reader DDSHST_Reader_T;
136 
137 struct DDSHST_ReaderSampleEntry;
138 
139 /*ci
140  * \brief Implementation independent reference to a sample in the
141  * reader history cache
142  */
143 typedef struct DDSHST_ReaderSampleEntry* DDSHST_ReaderSampleEntryRef_T;
144 
145 struct DDSHST_ReaderKeyEntry;
146 
147 /*ci
148  * \brief Implementation independent reference to a key in the
149  * reader history cache
150  */
151 typedef struct DDSHST_ReaderKeyEntry* DDSHST_ReaderKeyEntryRef_T;
152 
153 /*ci
154  * \brief Implementation independent reader cache sample
155  */
156 typedef struct DDSHST_ReaderSample
157 {
158  /*ci
159  * \brief Payload data, opaque to the cache and managed outside the cache,
160  * may by NULL for meta-samples.
161  */
162  void *_user_data;
163 
164  /*ci
165  * \brief Pointer to inline parameters for this sample, managed outside the
166  * cache
167  */
168  void *_param;
169 
170  /*ci
171  * \brief Pointer meta information about the sample, memory owner by
172  * history implementation
173  */
174  struct DDS_SampleInfo *_info;
175 
176  /*ci
177  * \brief Status information related to the sample, such as disposed
178  */
179  DDS_UnsignedLong status_info;
180 
181  /*ci
182  * \brief Reference to the corresponding entry in the implementation specific
183  * cache
184  */
185  DDSHST_ReaderSampleEntryRef_T _ref;
186 } DDSHST_ReaderSample_T;
187 
188 #define T DDSHST_ReaderSample_T
189 #define TSeq DDSHST_ReaderSample_TSeq
190 #include <reda/reda_sequence_decl.h>
191 
192 /*ci
193  * \brief Base-class properties for the DDS reader history cache
194  */
195 struct DDSHST_ReaderProperty
196 {
197  /*ci
198  * \brief Inherit from a component
199  */
200  struct RT_ComponentProperty _parent;
201 
202  /*ci
203  * \brief Pointer to the qos policy for the DDS reader that uses the history
204  * cache
205  */
206  struct DDS_DataReaderQos *qos;
207 
208  /*ci
209  * \brief Timer to use if timeouts are needed
210  */
211  OSAPI_Timer_T timer;
212 };
213 
214 /*ci
215  * \def DDSHST_ReaderProperty_INITIALIZER
216  * \brief Constant to initialize \ref DDSHST_ReaderProperty
217  */
218 #define DDSHST_ReaderProperty_INITIALIZER \
219 {\
220  RT_ComponentProperty_INITIALIZER,\
221  NULL,\
222  NULL \
223 }
224 
225 /*ci
226  * \brief Definition of the \ref DDSHST_ReaderListener on_sample_removed callback
227  *
228  * \details
229  * When the history cache removes a sample it calls this listener if it is
230  * installed.
231  *
232  * \param[in] rh The history cache
233  * \param[in] listener_data Opaque pointer to listener data
234  * \param[in] key The key the sample belonged too
235  * \param[in] sample The sample being removed
236  */
237 typedef void
238 (*DDSHST_ReaderListener_OnSampleRemovedFunc)(
239  struct DDSHST_Reader *rh,
240  void *listener_data,
241  DDS_InstanceHandle_t *key,
242  DDSHST_ReaderSample_T *sample);
243 
244 /*ci
245  * \brief Definition of the \ref DDSHST_ReaderListener on_key_removed callback
246  *
247  * \details
248  * When the history cache removes a key it calls this listener if it is
249  * installed.
250  *
251  * \param[in] rh The history cache
252  * \param[in] listener_data Opaque pointer to listener data
253  * \param[in] key The key being removed
254  */
255 typedef void
256 (*DDSHST_ReaderListener_OnKeyRemovedFunc)(
257  struct DDSHST_Reader *rh,
258  void *listener_data,
259  DDS_InstanceHandle_t *key);
260 
261 /*ci
262  * \brief Definition of the \ref DDSHST_ReaderListener on_deadline_missed callback
263  *
264  * \details
265  * When an instance is not being updated according to the deadline the cache
266  * calls this listener if it is installed.
267  *
268  * \param[in] rh The history cache
269  * \param[in] listener_data Opaque pointer to listener data
270  * \param[in] key The key that missed its deadline
271  */
272 typedef void
273 (*DDSHST_ReaderListener_OnDeadlineMissedFunc)(
274  struct DDSHST_Reader *rh,
275  void *listener_data,
276  DDS_InstanceHandle_t *key);
277 
278 /*ci
279  * \brief Definition of the \ref DDSHST_ReaderListener on_data_available callback
280  *
281  * \details
282  * When new data is available in the history cache this listener is called
283  * if it is installed.
284  *
285  * \param[in] rh The history cache
286  * \param[in] listener_data Opaque pointer to listener data
287  * \param[in] key The key data is available in
288  * \param[in] sample The new data
289  */
290 typedef void
291 (*DDSHST_ReaderListener_OnDataAvailableFunc)(
292  struct DDSHST_Reader *rh,
293  void *listener_data,
294  DDS_InstanceHandle_t *key,
295  DDSHST_ReaderSample_T *sample);
296 
297 /*ci
298  * \brief Definition of the \ref DDSHST_ReaderListener on_sample_rejected callback
299  *
300  * \details
301  * If a sample is rejected from the history cache this listener is called
302  * if it is installed.
303  *
304  * \param[in] rh The history cache
305  * \param[in] listener_data Opaque pointer to listener data
306  * \param[in] key The key that was rejected
307  * \param[in] reason The reason the sample was rejected
308  */
309 typedef void
310 (*DDSHST_ReaderListener_OnSampleRejectedFunc)(
311  struct DDSHST_Reader *rh,
312  void *listener_data,
313  DDS_InstanceHandle_t *key,
314  DDS_SampleRejectedStatusKind reason);
315 
316 /*ci
317  * \brief Definition of the \ref DDSHST_ReaderListener on_sample_lost callback
318  *
319  * \details
320  * When the history cache determines a sample is permanently lost
321  * the history cache calls this listener if it is installed.
322  *
323  * \param[in] rh The history cache
324  * \param[in] listener_data Opaque pointer to listener data
325  * \param[in] sample_info The sample info structure with additional information
326  * about the last sample
327  * (instance_handle, publication_handle)
328  * \param[in] reason The reason the sample was lost
329  */
330 typedef void
331 (*DDSHST_ReaderListener_OnSampleLostFunc)(
332  struct DDSHST_Reader *rh,
333  void *listener_data,
334  struct DDS_SampleInfo *sample_info,
335  DDS_SampleLostStatusKind reason);
336 
337 /*ci
338  * \brief Definition of the \ref DDSHST_ReaderListener on_instance_replaced callback
339  *
340  * \details
341  * When the history cache replaces an instance in the history cache it calls
342  * this listener if it is installed.
343  *
344  * \param[in] rh The history cache
345  * \param[in] listener_data Opaque pointer to listener data
346  * \param[in] replaced_key The key that was replaced
347  * \param[in] replaced_by_key The new key
348  * \param[in] publisher The publisher publishing the replacement key
349  * \param[in] min_removed_samples Minimum number of samples removed due to a
350  * key being replaced.
351  */
352 typedef void
353 (*DDSHST_ReaderListener_OnInstanceReplacedFunc)(
354  struct DDSHST_Reader *rh,
355  void *listener_data,
356  DDS_InstanceHandle_t *replaced_key,
357  DDS_InstanceHandle_t *replaced_by_key,
358  DDS_InstanceHandle_t *publisher,
359  DDS_Long min_removed_samples);
360 
361 /*ci
362  * \brief Base-class for DDS Reader history listener
363  */
364 struct DDSHST_ReaderListener
365 {
366  /*ci
367  * \brief Inherit from parent class
368  */
369  struct RT_ComponentListener _parent;
370 
371  /*ci
372  * \brief Called when the cache removed a sample
373  */
374  DDSHST_ReaderListener_OnSampleRemovedFunc on_sample_removed;
375 
376  /*ci
377  * \brief Called when the cache removed a key
378  */
379  DDSHST_ReaderListener_OnKeyRemovedFunc on_key_removed;
380 
381  /*ci
382  * \brief Called when the cache when new data is available in the cache
383  */
384  DDSHST_ReaderListener_OnDataAvailableFunc on_data_available;
385 
386  /*ci
387  * \brief Called when the cache detected deadline missed on an instance
388  */
389  DDSHST_ReaderListener_OnDeadlineMissedFunc on_deadline_missed;
390 
391  /*ci
392  * \brief Called when the cache rejected a sample
393  */
394  DDSHST_ReaderListener_OnSampleRejectedFunc on_sample_rejected;
395 
396  /*ci
397  * \brief Called when the cache detected loss of samples
398  */
399  DDSHST_ReaderListener_OnSampleLostFunc on_sample_lost;
400 
401  /*ci
402  * \brief Called when the cache forcefully replaced an instance
403  */
404  DDSHST_ReaderListener_OnInstanceReplacedFunc on_instance_replaced;
405 
406  /*ci
407  * \brief Opaque listener data passed back to listener functions
408  */
409  void *listener_data;
410 };
411 
412 /*ci
413  * \brief Constant to initialize \ref DDSHST_ReaderListener
414  */
415 #define DDSHST_ReaderListener_INITIALIZE {\
416  RT_ComponentListener_INITIALIZER,\
417  NULL,\
418  NULL,\
419  NULL,\
420  NULL,\
421  NULL,\
422  NULL,\
423  NULL,\
424  NULL\
425 }
426 
427 /* ------------------------------ Life-cycle -------------------------------- */
428 /*ci
429  * \brief Definition of \ref RT_ComponentFactory delete_component method
430  *
431  * \param[in] self The reader history instance to delete
432  *
433  * \sa \ref RT_ComponentFactoryI
434  */
435 typedef void
436 (*DDSHST_Reader_deleteFunc)(struct DDSHST_Reader *self);
437 
438 /*ci
439  * \brief Definition of \ref RT_ComponentFactory create_component method
440  *
441  * \param[in] property The component property
442  * \param[in] listener The component listener
443  *
444  * \return A reference to a new reader cache on success, NULL otherwise
445  *
446  * \sa \ref RT_ComponentFactoryI
447  */
448 FUNCTION_MUST_TYPEDEF(
449 struct DDSHST_Reader*
450 (*DDSHST_Reader_createFunc)(const struct DDSHST_ReaderProperty *const property,
451  const struct DDSHST_ReaderListener *const listener)
452 )
453 
454 /* ------------------------------ Methods ----------------------------------- */
455 /*ci
456  * \brief Definition of the \ref DDSHST_ReaderI reserve_entry method
457  *
458  * \param[in] self The history cache
459  * \param[in] rw The remote writer the reservation is for
460  * \param[in] key The key the reservation is for
461  * \param[out] sample_info A pointer to a sample info structure for this
462  * sample, memory owned by the queue
463  * \param[in] strength The current strength for the remote writer the
464  * reservation for
465  * \param[in] sample_sn The SN for this entry
466  * \param[out] reject_reason If the reservation failed, this is the reason
467  *
468  * \return A reference to a reservation, NULL otherwise
469  *
470  * \sa \ref DDSHST_Reader_reserve_entry, \ref DDSHST_ReaderI
471  */
472 FUNCTION_MUST_TYPEDEF(
473 DDSHST_ReaderSampleEntryRef_T
474 (*DDSHST_Reader_reserve_entryFunc)(
475  struct DDSHST_Reader *self,
476  DDS_InstanceHandle_t *rw,
477  DDS_InstanceHandle_t *key,
478  struct DDS_SampleInfo **sample_info,
479  DDS_Long strength,
480  struct REDA_SequenceNumber *sample_sn,
481  DDS_SampleRejectedStatusKind *reject_reason)
482 )
483 
484 /*ci
485  * \brief Definition of the \ref DDSHST_ReaderI return_entry method
486  *
487  * \param[in] self self
488  * \param[in] entry reservation to cancel
489  *
490  * \sa \ref DDSHST_Reader_return_entry, \ref DDSHST_ReaderI
491  */
492 typedef void
493 (*DDSHST_Reader_return_entryFunc)(struct DDSHST_Reader *self,
494  DDSHST_ReaderSampleEntryRef_T entry);
495 
496 /*ci
497  * \brief Definition of the \ref DDSHST_ReaderI commit method
498  *
499  * \param[in] self The history cache
500  * \param[in] rw The remote writer to commit samples for
501  * \param[in] sn The first non committable sequence number
502  * \param[in] strength The strength of the writer
503  *
504  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
505  * \ref DDSHST_ReturnCode_T on failure
506  *
507  * \sa \ref DDSHST_Reader_commit, \ref DDSHST_ReaderI
508  */
509 FUNCTION_MUST_TYPEDEF(
510 DDSHST_ReturnCode_T
511 (*DDSHST_Reader_commitFunc)(struct DDSHST_Reader *self,
512  DDS_InstanceHandle_t *rw,
513  struct REDA_SequenceNumber *sn,
514  DDS_Long strength)
515 )
516 
517 /*ci
518  * \brief Definition of the \ref DDSHST_ReaderI add_and_commit method
519  *
520  * \param[in] rh The history cache
521  * \param[in] entry The reserved entry to commit
522  * \param[in] sample The sample associated with the reservation
523  * \param[in] commit_sn The first non-committable sequence number
524  *
525  * \sa \ref DDSHST_Reader_add_and_commit, \ref DDSHST_ReaderI
526  */
527 FUNCTION_MUST_TYPEDEF(
528 DDSHST_ReturnCode_T
529 (*DDSHST_Reader_add_and_commitFunc)(struct DDSHST_Reader *rh,
530  DDSHST_ReaderSampleEntryRef_T entry,
531  DDSHST_ReaderSample_T *sample,
532  struct REDA_SequenceNumber *commit_sn)
533 )
534 
535 /*ci
536  * \brief Definition of the \ref DDSHST_ReaderI post_event method
537  *
538  * \param[in] self The history cache
539  * \param[in] event The event that occurred
540  * \param[in] now The time the event occurred
541  *
542  * \sa \ref DDSHST_Reader_post_event, \ref DDSHST_ReaderI
543  */
544 typedef void
545 (*DDSHST_Reader_post_eventFunc)(struct DDSHST_Reader *self,
546  struct DDSHST_ReaderEvent *event,
547  struct OSAPI_NtpTime *now);
548 
549 /*ci
550  * \brief Definition of the \ref DDSHST_ReaderI read_or_take method
551  *
552  * \param[in] self The history cache to read from
553  * \param[inout] sample_ptr_array A sequence of pointers to samples
554  * \param[inout] info_array A sequence of pointers to sample info
555  * \param[in] sample_count The actual number of samples returned
556  * \param[in] a_handle The instance to return (NIL is any instance)
557  * \param[in] max_samples The max number of samples to return (including
558  * the meta sample)
559  * \param[in] sample_states The requested sample state
560  * \param[in] view_states The requested view state
561  * \param[in] instance_states The requested instance state
562  * \param[in] take Whether this removes (RTI_TRUE) or leaves
563  * samples in the cache (RTI_FALSE)
564  *
565  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
566  * \ref DDSHST_ReturnCode_T on failure
567  *
568  * \sa \ref DDSHST_Reader_read_or_take, \ref DDSHST_ReaderI
569  */
570 FUNCTION_MUST_TYPEDEF(
571 DDS_ReturnCode_t
572 (*DDSHST_Reader_read_or_takeFunc)(struct DDSHST_Reader *self,
573  void ***sample_ptr_array,
574  struct DDS_SampleInfo ***info_array,
575  DDS_Long *sample_count,
576  const DDS_InstanceHandle_t *a_handle,
577  DDS_Long max_samples,
578  DDS_SampleStateMask sample_states,
579  DDS_ViewStateMask view_states,
580  DDS_InstanceStateMask instance_states,
581  DDS_Boolean take)
582 )
583 
584 /*ci
585  * \brief Definition of the \ref DDSHST_ReaderI finish_read_or_take method
586  *
587  * \param[in] self The history cache to return the sequences to
588  * \param[in] sample_ptr_array A sequence of pointers to samples to return
589  * \param[in] info_array A sequence of pointers to sample info to return
590  * \param[in] sample_count The number of samples to return in each sequence
591  * \param[in] taken Whether the samples where taken or not
592  *
593  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
594  * \ref DDSHST_ReturnCode_T on failure
595  *
596  * \sa \ref DDSHST_Reader_finish_read_or_take, \ref DDSHST_ReaderI
597  */
598 FUNCTION_MUST_TYPEDEF(
599 DDS_ReturnCode_t
600 (*DDSHST_Reader_finish_read_or_takeFunc)(struct DDSHST_Reader *self,
601  void ***sample_ptr_array,
602  struct DDS_SampleInfo ***info_array,
603  DDS_Long sample_count,
604  DDS_Boolean taken)
605 )
606 
607 /*ci
608  * \brief Definition of the \ref DDSHST_ReaderI lookup_key method
609  *
610  * \param[in] self The history cache
611  * \param[in] key The key entry to search for
612  *
613  * \return A key entry on success, NULL if the entry was not found
614  *
615  * \sa \ref DDSHST_Reader_lookup_key, \ref DDSHST_ReaderI
616  */
617 FUNCTION_MUST_TYPEDEF(
618 DDSHST_ReaderKeyEntryRef_T
619 (*DDSHST_Reader_lookup_keyFunc)(struct DDSHST_Reader* self,
620  const DDS_InstanceHandle_t *const key)
621 )
622 
623 /*ci
624  * \brief Definition of the DDSHST_Reader history interface
625  */
626 struct DDSHST_ReaderI
627 {
628  /*ci
629  * \brief The base-class listener
630  */
631  struct RT_ComponentI _parent;
632 
633  /*ci
634  * \brief Method to return an entry to the cache
635  */
636  DDSHST_Reader_return_entryFunc return_entry;
637 
638  /*ci
639  * \brief Method to read or take an entry from the cache
640  */
641  DDSHST_Reader_read_or_takeFunc read_or_take;
642 
643  /*ci
644  * \brief Method to return a loan to the cache
645  */
646  DDSHST_Reader_finish_read_or_takeFunc finish_read_or_take;
647 
648  /*ci
649  * \brief Method to post an event to the cache
650  */
651  DDSHST_Reader_post_eventFunc post_event;
652 
653  /*ci
654  * \brief Method to lookup the key from the cache
655  */
656  DDSHST_Reader_lookup_keyFunc lookup_key;
657 
658  /*ci
659  * \brief Method to reserve a spot in the cache
660  */
661  DDSHST_Reader_reserve_entryFunc reserve_entry;
662 
663  /*ci
664  * \brief Method to add a reservation to the cache and commit the
665  * entries
666  */
667  DDSHST_Reader_add_and_commitFunc add_and_commit;
668 
669  /*ci
670  * \brief Method to commit existing entries in the cac (if possible)
671  */
672  DDSHST_Reader_commitFunc commit;
673 };
674 
675 /*ci
676  * \brief Create a new instance of the reader history cache
677  */
678 #define DDSHST_ReaderFactory_create_component(f_,p_,l_) \
679 (struct DDSHST_Reader*)((f_)->intf)->create_component(f_,p_,l_)
680 
681 /*ci
682  * \brief Delete an instance of the reader history cache
683  */
684 #define DDSHST_ReaderFactory_delete_component(f_,c_) \
685  ((f_)->intf)->delete_component(f_,(RT_Component_T*)(c_))
686 
687 /*ci
688  * \brief Implementation of the DDSHST_Reader_reserve_entry function
689  *
690  * \details
691  * This function tries to reserve an entry in the cache based on the current
692  * resource limits. A reserved entry can either be committed to the queue
693  * or returned unused (cancelled). If an entry is returned (not called decided
694  * to not use it), all operations that took place in the reservation are
695  * reversed. That is, any resource allocated are freed.
696  *
697  * \param[in] self_ The history cache
698  * \param[in] rw_ The remote writer the reservation is for
699  * \param[in] key_ The key the reservation is for
700  * \param[out] si_ A pointer to a sample info structure for this
701  * sample, memory owned by the queue
702  * \param[in] strength_ The current strength for the remote writer the
703  * reservation for
704  * \param[in] sample_sn_ The SN for this entry
705  * \param[out] reject_reason_ If the reservation failed, this is the reason
706  *
707  * \return A reference to a reservation, NULL otherwise
708  */
709 #define DDSHST_Reader_reserve_entry(self_,rw_,key_,si_,strength_,\
710  sample_sn_,reject_reason_) \
711  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->reserve_entry(\
712  self_,rw_,key_,si_,strength_,\
713  sample_sn_,reject_reason_)
714 /*ci
715  * \brief Return/Cancel a queue reservation
716  *
717  * \details
718  *
719  * Return a previous reservation. Returning a reservation has no effect
720  * on the queue, and any resources allocated are returned.
721  *
722  * \param[in] self_ self
723  * \param[in] entry_ reservation to cancel
724  *
725  * \sa \ref RHSM_History_reserve_entry
726  */
727 #define DDSHST_Reader_return_entry(self_,entry_) \
728  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->return_entry(\
729  self_,entry_)
730 
731 /*ci
732  * \brief Add a reserved sample to the queue and commit one or more
733  *
734  * \details
735  * When a reservation is made the entry does not exist in the cache, only
736  * a sample to fill in exists. If the holder of the reservation decides to
737  * keep the sample it must be added. When a new sample is added it may also
738  * result in 1 or more samples being committed (for example if the newly
739  * added sample completes a sequence of samples).
740  *
741  * \param[in] self_ The history cache
742  * \param[in] entry_ The reserved entry to commit
743  * \param[in] sample_ The sample associated with the reservation
744  * \param[in] sn_ The first non-committable sequence number
745  *
746  * \sa \ref RHSM_History_reserve_entry
747  */
748 #define DDSHST_Reader_add_and_commit(self_,entry_,sample_,sn_) \
749  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->add_and_commit(\
750  self_,entry_,sample_,sn_)
751 
752 /*ci
753  * \brief Commit all cached samples up to a specific SN for a remote writer
754  *
755  * \details
756  * The history cache may store samples received out of order to improve
757  * performance for reliable communication. If samples are received out of
758  * order there may be a backlog of samples until a sample is received that
759  * completes a sequence of samples. This function adds all these samples.
760  *
761  * \param[in] self_ The history cache
762  * \param[in] rw_ The remote writer to commit samples for
763  * \param[in] sn_ The first non commitable sequence number
764  * \param[in] s_ The strength of the writer
765  *
766  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
767  * \ref DDSHST_ReturnCode_T on failure
768  */
769 #define DDSHST_Reader_commit(self_,rw_,sn_,s_) \
770  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->commit(\
771  self_,rw_,sn_,s_)
772 
773 /*
774  * \brief Read or take 1 or more samples matching a particular state from the
775  * history cache
776  *
777  * \details
778  * Return 0 or more samples and sample info. The sample_ptr_array and
779  * info_array must be pre-allocated to hold at least max_samples
780  * pointers. Note that the history _always_ operates on pointer to samples,
781  * it has no knowledge about types.
782  *
783  * \param[in] self_ The history cache to read from
784  * \param[inout] sample_arr_ A sequence of pointers to samples
785  * \param[inout] info_arr_ A sequence of pointers to sample info
786  * \param[in] count_ The actual number of samples returned
787  * \param[in] handle_ The instance to return (NIL is any instance)
788  * \param[in] max_samples_ The max number of samples to return (including
789  * the meta sample)
790  * \param[in] sample_states_ The requested sample state
791  * \param[in] view_states_ The requested view state
792  * \param[in] instance_states_ The requested instance state
793  * \param[in] take_ Whether this removes (RTI_TRUE) or leaves
794  * samples in the cache (RTI_FALSE)
795  *
796  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
797  * \ref DDSHST_ReturnCode_T on failure
798  */
799 #define DDSHST_Reader_read_or_take(self_,\
800 sample_arr_,info_arr_,count_,handle_,max_samples_,sample_states_,view_states_,\
801  instance_states_,take_) \
802  ((struct DDSHST_ReaderI*)(\
803  (self_)->_parent._intf))->read_or_take(self_,\
804  sample_arr_,info_arr_,count_,handle_,max_samples_,\
805  sample_states_,view_states_,instance_states_,take_)
806 
807 /*ci
808  * \brief Return a loan after calling \ref RHSM_History_read_or_take
809  *
810  * \param[in] self_ The history cache to return the sequences to
811  * \param[in] sample_seq_ A sequence of pointers to samples to return
812  * \param[in] info_seq_ A sequence of pointers to sample info to return
813  * \param[in] count_ The number of samples to return (same count for each
814  * sequence)
815  * \param[in] take_ Whether the samples where taken or not
816  *
817  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
818  * \ref DDSHST_ReturnCode_T on failure
819  *
820  * \sa \ref RHSM_History_read_or_take
821  */
822 #define DDSHST_Reader_finish_read_or_take(self_,sample_seq_,info_seq_,count_,take_) \
823  ((struct DDSHST_ReaderI*)(\
824  (self_)->_parent._intf))->finish_read_or_take(self_,\
825  sample_seq_,info_seq_,count_,take_)
826 
827 /*ci
828  * \brief Post an external event to the history cache
829  *
830  * \details
831  * This function is the entry point to signal the queue for various
832  * types of external events.
833  *
834  * \param[in] self_ The history cache
835  * \param[in] event_ The event that occurred
836  * \param[in] time_ The time the event occurred
837  */
838 #define DDSHST_Reader_post_event(self_,event_,time_) \
839  ((struct DDSHST_ReaderI*)(\
840  (self_)->_parent._intf))->post_event(self_,event_,time_)
841 
842 /*ci
843  * \brief Find and return a pointer to a key entry based on the instance handle
844  *
845  * \param[in] self_ The history cache
846  * \param[in] key_ The key entry to search for
847  *
848  * \return A key entry on success, NULL if the entry was not found
849  */
850 #define DDSHST_Reader_lookup_key(self_,key_) \
851  ((struct DDSHST_ReaderI*)(\
852  (self_)->_parent._intf))->lookup_key(self_,key_)
853 
854 #ifdef __cplusplus
855 } /* extern "C" */
856 #endif
857 
858 #endif /* dds_c_rh_plugin_h */
859 
860 /*ci @} */
RTI Connext DDS Micro Version 2.4.8 Copyright © Tue Apr 12 2016 Real-Time Innovations, Inc