RTI Connext DDS Micro  Version 2.4.11
 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 Definition of the \ref DDSHST_ReaderListener on_sample_commited callback
363  *
364  * \details
365  * Normally when add_and_commit and commit is called the samples are added to
366  * the commit queue and are readily available for reuse by being reclaimed
367  * (in the case of KEEP_LAST).
368  *
369  * However, in cases where resource limits are exceeded, such as
370  * max_samples_per_instance, samples may be committed at a later time
371  * when resources are freed up. This is done asynchronously to the receive thread
372  * This listener notifies that samples have been committed and are available to be
373  * reclaimed. It is up to the listener to pass the information downstream to
374  * RTPS (or other layer).
375  *
376  *
377  * \param[in] rh The history cache
378  * \param[in] listener_data Opaque pointer to listener data
379  */
380 typedef void
381 (*DDSHST_ReaderListener_OnSampleCommittedFunc)(struct DDSHST_Reader *rh,
382  void *listener_data,
383  DDS_InstanceHandle_t *publisher,
384  DDS_Long committed_samples);
385 
386 /*ci
387  * \brief Base-class for DDS Reader history listener
388  */
389 struct DDSHST_ReaderListener
390 {
391  /*ci
392  * \brief Inherit from parent class
393  */
394  struct RT_ComponentListener _parent;
395 
396  /*ci
397  * \brief Called when the cache removed a sample
398  */
399  DDSHST_ReaderListener_OnSampleRemovedFunc on_sample_removed;
400 
401  /*ci
402  * \brief Called when the cache removed a key
403  */
404  DDSHST_ReaderListener_OnKeyRemovedFunc on_key_removed;
405 
406  /*ci
407  * \brief Called when the cache when new data is available in the cache
408  */
409  DDSHST_ReaderListener_OnDataAvailableFunc on_data_available;
410 
411  /*ci
412  * \brief Called when the cache detected deadline missed on an instance
413  */
414  DDSHST_ReaderListener_OnDeadlineMissedFunc on_deadline_missed;
415 
416  /*ci
417  * \brief Called when the cache rejected a sample
418  */
419  DDSHST_ReaderListener_OnSampleRejectedFunc on_sample_rejected;
420 
421  /*ci
422  * \brief Called when the cache detected loss of samples
423  */
424  DDSHST_ReaderListener_OnSampleLostFunc on_sample_lost;
425 
426  /*ci
427  * \brief Called when the cache forcefully replaced an instance
428  */
429  DDSHST_ReaderListener_OnInstanceReplacedFunc on_instance_replaced;
430 
431  /*ci
432  * \brief Called when new samples are added to the committed cache.
433  */
434  DDSHST_ReaderListener_OnSampleCommittedFunc on_sample_committed;
435 
436  /*ci
437  * \brief Opaque listener data passed back to listener functions
438  */
439  void *listener_data;
440 };
441 
442 /*ci
443  * \brief Constant to initialize \ref DDSHST_ReaderListener
444  */
445 #define DDSHST_ReaderListener_INITIALIZE {\
446  RT_ComponentListener_INITIALIZER,\
447  NULL,\
448  NULL,\
449  NULL,\
450  NULL,\
451  NULL,\
452  NULL,\
453  NULL,\
454  NULL,\
455  NULL\
456 }
457 
458 /* ------------------------------ Life-cycle -------------------------------- */
459 /*ci
460  * \brief Definition of \ref RT_ComponentFactory delete_component method
461  *
462  * \param[in] self The reader history instance to delete
463  *
464  * \sa \ref RT_ComponentFactoryI
465  */
466 typedef void
467 (*DDSHST_Reader_deleteFunc)(struct DDSHST_Reader *self);
468 
469 /*ci
470  * \brief Definition of \ref RT_ComponentFactory create_component method
471  *
472  * \param[in] property The component property
473  * \param[in] listener The component listener
474  *
475  * \return A reference to a new reader cache on success, NULL otherwise
476  *
477  * \sa \ref RT_ComponentFactoryI
478  */
479 FUNCTION_MUST_TYPEDEF(
480 struct DDSHST_Reader*
481 (*DDSHST_Reader_createFunc)(const struct DDSHST_ReaderProperty *const property,
482  const struct DDSHST_ReaderListener *const listener)
483 )
484 
485 /* ------------------------------ Methods ----------------------------------- */
486 /*ci
487  * \brief Definition of the \ref DDSHST_ReaderI reserve_entry method
488  *
489  * \param[in] self The history cache
490  * \param[in] rw The remote writer the reservation is for
491  * \param[in] key The key the reservation is for
492  * \param[out] sample_info A pointer to a sample info structure for this
493  * sample, memory owned by the queue
494  * \param[in] strength The current strength for the remote writer
495  * the reservation for
496  * \param[in] sample_sn The SN for this entry
497  * \param[in] sample_virtual_sn The SN for this entry
498  * \param[out] reject_reason If the reservation failed, this is the reason
499  *
500  * \return A reference to a reservation, NULL otherwise
501  *
502  * \sa \ref DDSHST_Reader_reserve_entry, \ref DDSHST_ReaderI
503  */
504 FUNCTION_MUST_TYPEDEF(
505 DDSHST_ReaderSampleEntryRef_T
506 (*DDSHST_Reader_reserve_entryFunc)(
507  struct DDSHST_Reader *self,
508  DDS_InstanceHandle_t *rw,
509  DDS_InstanceHandle_t *key,
510  struct DDS_SampleInfo **sample_info,
511  DDS_Long strength,
512  struct REDA_SequenceNumber *sample_sn,
513  struct REDA_SequenceNumber *sample_virtual_sn,
514  DDS_SampleRejectedStatusKind *reject_reason)
515 )
516 
517 /*ci
518  * \brief Definition of the \ref DDSHST_ReaderI return_entry method
519  *
520  * \param[in] self self
521  * \param[in] entry reservation to cancel
522  *
523  * \sa \ref DDSHST_Reader_return_entry, \ref DDSHST_ReaderI
524  */
525 typedef void
526 (*DDSHST_Reader_return_entryFunc)(struct DDSHST_Reader *self,
527  DDSHST_ReaderSampleEntryRef_T entry);
528 
529 /*ci
530  * \brief Definition of the \ref DDSHST_ReaderI commit method
531  *
532  * \param[in] self The history cache
533  * \param[in] rw The remote writer to commit samples for
534  * \param[in] sn The first non committable sequence number
535  * \param[in] strength The strength of the writer
536  * \param[in] notify_on_commit Whether to post event upon sample commit
537  * \param[out] last_virtual_sn The virtual SN of the last committed sample
538  * \param[out] missing_vsn_ The number of missing vsn in a range
539  *
540  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
541  * \ref DDSHST_ReturnCode_T on failure
542  *
543  * \sa \ref DDSHST_Reader_commit, \ref DDSHST_ReaderI
544  */
545 FUNCTION_MUST_TYPEDEF(
546 DDSHST_ReturnCode_T
547 (*DDSHST_Reader_commitFunc)(struct DDSHST_Reader *self,
548  DDS_InstanceHandle_t *rw,
549  struct REDA_SequenceNumber *sn,
550  DDS_Long strength,
551  DDS_Boolean notify_on_commit,
552  struct REDA_SequenceNumber *last_virtual_sn,
553  DDS_UnsignedLong *missing_vsn);
554 )
555 
556 /*ci
557  * \brief Definition of the \ref DDSHST_ReaderI add_and_commit method
558  *
559  * \param[in] rh The history cache
560  * \param[in] entry The reserved entry to commit
561  * \param[in] sample The sample associated with the reservation
562  * \param[in] commit_sn The first non-committable sequence number
563  * \param[in] notify_on_commit Whether to post event upon sample commit
564  * \param[out] last_virtual_sn The virtual SN of the last committed sample
565  * \param[out] missing_vsn_ The number of missing vsn in a range
566  *
567  * \sa \ref DDSHST_Reader_add_and_commit, \ref DDSHST_ReaderI
568  */
569 FUNCTION_MUST_TYPEDEF(
570 DDSHST_ReturnCode_T
571 (*DDSHST_Reader_add_and_commitFunc)(struct DDSHST_Reader *rh,
572  DDSHST_ReaderSampleEntryRef_T entry,
573  DDSHST_ReaderSample_T *sample,
574  struct REDA_SequenceNumber *commit_sn,
575  DDS_Boolean notify_on_commit,
576  struct REDA_SequenceNumber *last_virtual_sn,
577  DDS_UnsignedLong *missing_vsn);
578 )
579 
580 /*ci
581  * \brief Definition of the \ref DDSHST_ReaderI post_event method
582  *
583  * \param[in] self The history cache
584  * \param[in] event The event that occurred
585  * \param[in] now The time the event occurred
586  *
587  * \sa \ref DDSHST_Reader_post_event, \ref DDSHST_ReaderI
588  */
589 typedef void
590 (*DDSHST_Reader_post_eventFunc)(struct DDSHST_Reader *self,
591  struct DDSHST_ReaderEvent *event,
592  struct OSAPI_NtpTime *now);
593 
594 /*ci
595  * \brief Definition of the \ref DDSHST_ReaderI read_or_take method
596  *
597  * \param[in] self The history cache to read from
598  * \param[inout] sample_ptr_array A sequence of pointers to samples
599  * \param[inout] info_array A sequence of pointers to sample info
600  * \param[in] sample_count The actual number of samples returned
601  * \param[in] a_handle The instance to return (NIL is any instance)
602  * \param[in] max_samples The max number of samples to return (including
603  * the meta sample)
604  * \param[in] sample_states The requested sample state
605  * \param[in] view_states The requested view state
606  * \param[in] instance_states The requested instance state
607  * \param[in] take Whether this removes (RTI_TRUE) or leaves
608  * samples in the cache (RTI_FALSE)
609  *
610  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
611  * \ref DDSHST_ReturnCode_T on failure
612  *
613  * \sa \ref DDSHST_Reader_read_or_take, \ref DDSHST_ReaderI
614  */
615 FUNCTION_MUST_TYPEDEF(
616 DDS_ReturnCode_t
617 (*DDSHST_Reader_read_or_takeFunc)(struct DDSHST_Reader *self,
618  void ***sample_ptr_array,
619  struct DDS_SampleInfo ***info_array,
620  DDS_Long *sample_count,
621  const DDS_InstanceHandle_t *a_handle,
622  DDS_Long max_samples,
623  DDS_SampleStateMask sample_states,
624  DDS_ViewStateMask view_states,
625  DDS_InstanceStateMask instance_states,
626  DDS_Boolean take)
627 )
628 
629 /*ci
630  * \brief Definition of the \ref DDSHST_ReaderI finish_read_or_take method
631  *
632  * \param[in] self The history cache to return the sequences to
633  * \param[in] sample_ptr_array A sequence of pointers to samples to return
634  * \param[in] info_array A sequence of pointers to sample info to return
635  * \param[in] sample_count The number of samples to return in each sequence
636  * \param[in] taken Whether the samples where taken or not
637  *
638  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
639  * \ref DDSHST_ReturnCode_T on failure
640  *
641  * \sa \ref DDSHST_Reader_finish_read_or_take, \ref DDSHST_ReaderI
642  */
643 FUNCTION_MUST_TYPEDEF(
644 DDS_ReturnCode_t
645 (*DDSHST_Reader_finish_read_or_takeFunc)(struct DDSHST_Reader *self,
646  void ***sample_ptr_array,
647  struct DDS_SampleInfo ***info_array,
648  DDS_Long sample_count,
649  DDS_Boolean taken)
650 )
651 
652 /*ci
653  * \brief Definition of the \ref DDSHST_ReaderI lookup_key method
654  *
655  * \param[in] self The history cache
656  * \param[in] key The key entry to search for
657  *
658  * \return A key entry on success, NULL if the entry was not found
659  *
660  * \sa \ref DDSHST_Reader_lookup_key, \ref DDSHST_ReaderI
661  */
662 FUNCTION_MUST_TYPEDEF(
663 DDSHST_ReaderKeyEntryRef_T
664 (*DDSHST_Reader_lookup_keyFunc)(struct DDSHST_Reader* self,
665  const DDS_InstanceHandle_t *const key)
666 )
667 
668 /*ci
669  * \brief Definition of the DDSHST_Reader history interface
670  */
671 struct DDSHST_ReaderI
672 {
673  /*ci
674  * \brief The base-class listener
675  */
676  struct RT_ComponentI _parent;
677 
678  /*ci
679  * \brief Method to return an entry to the cache
680  */
681  DDSHST_Reader_return_entryFunc return_entry;
682 
683  /*ci
684  * \brief Method to read or take an entry from the cache
685  */
686  DDSHST_Reader_read_or_takeFunc read_or_take;
687 
688  /*ci
689  * \brief Method to return a loan to the cache
690  */
691  DDSHST_Reader_finish_read_or_takeFunc finish_read_or_take;
692 
693  /*ci
694  * \brief Method to post an event to the cache
695  */
696  DDSHST_Reader_post_eventFunc post_event;
697 
698  /*ci
699  * \brief Method to lookup the key from the cache
700  */
701  DDSHST_Reader_lookup_keyFunc lookup_key;
702 
703  /*ci
704  * \brief Method to reserve a spot in the cache
705  */
706  DDSHST_Reader_reserve_entryFunc reserve_entry;
707 
708  /*ci
709  * \brief Method to add a reservation to the cache and commit the
710  * entries
711  */
712  DDSHST_Reader_add_and_commitFunc add_and_commit;
713 
714  /*ci
715  * \brief Method to commit existing entries in the cac (if possible)
716  */
717  DDSHST_Reader_commitFunc commit;
718 };
719 
720 /*ci
721  * \brief Create a new instance of the reader history cache
722  */
723 #define DDSHST_ReaderFactory_create_component(f_,p_,l_) \
724 (struct DDSHST_Reader*)((f_)->intf)->create_component(f_,p_,l_)
725 
726 /*ci
727  * \brief Delete an instance of the reader history cache
728  */
729 #define DDSHST_ReaderFactory_delete_component(f_,c_) \
730  ((f_)->intf)->delete_component(f_,(RT_Component_T*)(c_))
731 
732 /*ci
733  * \brief Implementation of the DDSHST_Reader_reserve_entry function
734  *
735  * \details
736  * This function tries to reserve an entry in the cache based on the current
737  * resource limits. A reserved entry can either be committed to the queue
738  * or returned unused (cancelled). If an entry is returned (not called decided
739  * to not use it), all operations that took place in the reservation are
740  * reversed. That is, any resource allocated are freed.
741  *
742  * \param[in] self_ The history cache
743  * \param[in] rw_ The remote writer the reservation is for
744  * \param[in] key_ The key the reservation is for
745  * \param[out] si_ A pointer to a sample info structure for this
746  * sample, memory owned by the queue
747  * \param[in] strength_ The current strength for the remote writer
748  * the reservation for
749  * \param[in] sample_sn_ The SN for this entry
750  * \param[in] sample_virtual_sn_ The virtual SN for this entry
751  * \param[out] reject_reason_ If the reservation failed, this is the reason
752  *
753  * \return A reference to a reservation, NULL otherwise
754  */
755 #define DDSHST_Reader_reserve_entry(self_,rw_,key_,si_,strength_,\
756  sample_sn_,sample_virtual_sn_,\
757  reject_reason_) \
758  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->reserve_entry(\
759  self_,rw_,key_,si_,strength_,\
760  sample_sn_,sample_virtual_sn_,reject_reason_)
761 /*ci
762  * \brief Return/Cancel a queue reservation
763  *
764  * \details
765  *
766  * Return a previous reservation. Returning a reservation has no effect
767  * on the queue, and any resources allocated are returned.
768  *
769  * \param[in] self_ self
770  * \param[in] entry_ reservation to cancel
771  *
772  * \sa \ref RHSM_History_reserve_entry
773  */
774 #define DDSHST_Reader_return_entry(self_,entry_) \
775  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->return_entry(\
776  self_,entry_)
777 
778 /*ci
779  * \brief Add a reserved sample to the queue and commit one or more
780  *
781  * \details
782  * When a reservation is made the entry does not exist in the cache, only
783  * a sample to fill in exists. If the holder of the reservation decides to
784  * keep the sample it must be added. When a new sample is added it may also
785  * result in 1 or more samples being committed (for example if the newly
786  * added sample completes a sequence of samples).
787  *
788  * \param[in] self_ The history cache
789  * \param[in] entry_ The reserved entry to commit
790  * \param[in] sample_ The sample associated with the reservation
791  * \param[in] sn_ The first non-committable sequence number
792  * \param[in] noc_ Whether to post event for committed samples
793  * \param[out] last_virtual_sn_ The virtual SN of the last committed sample
794  * \param[out] missing_vsn_ The number of missing vsn in a range
795  *
796  * \sa \ref RHSM_History_reserve_entry
797  */
798 #define DDSHST_Reader_add_and_commit(self_,entry_,sample_,sn_,noc_,\
799  last_virtual_sn_,missing_vsn_) \
800  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->add_and_commit(\
801  self_,entry_,sample_,sn_,noc_,last_virtual_sn_,missing_vsn_)
802 
803 /*ci
804  * \brief Commit all cached samples up to a specific SN for a remote writer
805  *
806  * \details
807  * The history cache may store samples received out of order to improve
808  * performance for reliable communication. If samples are received out of
809  * order there may be a backlog of samples until a sample is received that
810  * completes a sequence of samples. This function adds all these samples.
811  *
812  * \param[in] self_ The history cache
813  * \param[in] rw_ The remote writer to commit samples for
814  * \param[in] sn_ The first non commitable sequence number
815  * \param[in] s_ The strength of the writer
816  * \param[out] last_virtual_sn_ The virtual SN of the last committed sample
817  * \param[out] missing_vsn_ The number of missing vsn in a range
818  *
819  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
820  * \ref DDSHST_ReturnCode_T on failure
821  */
822 #define DDSHST_Reader_commit(self_,rw_,sn_,s_,noc_,last_virtual_sn_,missing_vsn_) \
823  ((struct DDSHST_ReaderI*)((self_)->_parent._intf))->commit(\
824  self_,rw_,sn_,s_,noc_,last_virtual_sn_,missing_vsn_)
825 
826 /*
827  * \brief Read or take 1 or more samples matching a particular state from the
828  * history cache
829  *
830  * \details
831  * Return 0 or more samples and sample info. The sample_ptr_array and
832  * info_array must be pre-allocated to hold at least max_samples
833  * pointers. Note that the history _always_ operates on pointer to samples,
834  * it has no knowledge about types.
835  *
836  * \param[in] self_ The history cache to read from
837  * \param[inout] sample_arr_ A sequence of pointers to samples
838  * \param[inout] info_arr_ A sequence of pointers to sample info
839  * \param[in] count_ The actual number of samples returned
840  * \param[in] handle_ The instance to return (NIL is any instance)
841  * \param[in] max_samples_ The max number of samples to return (including
842  * the meta sample)
843  * \param[in] sample_states_ The requested sample state
844  * \param[in] view_states_ The requested view state
845  * \param[in] instance_states_ The requested instance state
846  * \param[in] take_ Whether this removes (RTI_TRUE) or leaves
847  * samples in the cache (RTI_FALSE)
848  *
849  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
850  * \ref DDSHST_ReturnCode_T on failure
851  */
852 #define DDSHST_Reader_read_or_take(self_,\
853 sample_arr_,info_arr_,count_,handle_,max_samples_,sample_states_,view_states_,\
854  instance_states_,take_) \
855  ((struct DDSHST_ReaderI*)(\
856  (self_)->_parent._intf))->read_or_take(self_,\
857  sample_arr_,info_arr_,count_,handle_,max_samples_,\
858  sample_states_,view_states_,instance_states_,take_)
859 
860 /*ci
861  * \brief Return a loan after calling \ref RHSM_History_read_or_take
862  *
863  * \param[in] self_ The history cache to return the sequences to
864  * \param[in] sample_seq_ A sequence of pointers to samples to return
865  * \param[in] info_seq_ A sequence of pointers to sample info to return
866  * \param[in] count_ The number of samples to return (same count for each
867  * sequence)
868  * \param[in] take_ Whether the samples where taken or not
869  *
870  * \return DDSHST_RETCODE_SUCCESS on success, one of the standard
871  * \ref DDSHST_ReturnCode_T on failure
872  *
873  * \sa \ref RHSM_History_read_or_take
874  */
875 #define DDSHST_Reader_finish_read_or_take(self_,sample_seq_,info_seq_,count_,take_) \
876  ((struct DDSHST_ReaderI*)(\
877  (self_)->_parent._intf))->finish_read_or_take(self_,\
878  sample_seq_,info_seq_,count_,take_)
879 
880 /*ci
881  * \brief Post an external event to the history cache
882  *
883  * \details
884  * This function is the entry point to signal the queue for various
885  * types of external events.
886  *
887  * \param[in] self_ The history cache
888  * \param[in] event_ The event that occurred
889  * \param[in] time_ The time the event occurred
890  */
891 #define DDSHST_Reader_post_event(self_,event_,time_) \
892  ((struct DDSHST_ReaderI*)(\
893  (self_)->_parent._intf))->post_event(self_,event_,time_)
894 
895 /*ci
896  * \brief Find and return a pointer to a key entry based on the instance handle
897  *
898  * \param[in] self_ The history cache
899  * \param[in] key_ The key entry to search for
900  *
901  * \return A key entry on success, NULL if the entry was not found
902  */
903 #define DDSHST_Reader_lookup_key(self_,key_) \
904  ((struct DDSHST_ReaderI*)(\
905  (self_)->_parent._intf))->lookup_key(self_,key_)
906 
907 #ifdef __cplusplus
908 } /* extern "C" */
909 #endif
910 
911 #endif /* dds_c_rh_plugin_h */
912 
913 /*ci @} */
RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc