pragma Ada_2012; -- (c) Copyright, Real-Time Innovations, $Date:: 2012-02-16 #$ -- All rights reserved. -- -- No duplications, whole or partial, manual or electronic, may be made -- without express written permission. Any such copies, or -- revisions thereof, must display this notice unaltered. -- This code contains trade secrets of Real-Time Innovations, Inc. pragma Ada_2012; with DDS.DataReader; with DDS.DataReader_Impl; with DDS.ReadCondition; with RTIDDS.Low_Level.ndds_dds_c_dds_c_infrastructure_h; use RTIDDS.Low_Level.ndds_dds_c_dds_c_infrastructure_h;
with Ada.Unchecked_Conversion; with DDS.Treats_Generic; pragma Elaborate (DDS.Treats_Generic);
generic with package Treats is new DDS.Treats_Generic (<>);
use Treats;
package DDS.Typed_DataReader_Generic is
pragma Suppress (Elaboration_Check); type Ref is new DDS.DataReader_Impl.Ref with null record;
type Ref_Access is access all Ref'Class;
type Element_Type is record
Data : Data_Type_Access; Sample_Info : SampleInfo_Access; end record;
type Cursor is new DDS.Natural;
-- <<experimental>> <<extension>> Allows for creating an iterator of received_data sequence -- and info_seq type Container (<>) is limited new Ada.Finalization.Limited_Controlled with private with
Iterable => (First => I_First_Element, Element => I_Get_Element, Has_Element => I_Has_Element, Next => I_Advance); -- <<experimental>> <<extension>> function I_First_Element (Self : Container) return Cursor;
-- <<experimental>> <<extension>> function I_Advance (Self : Container; C : Cursor) return Cursor;
-- <<experimental>> <<extension>> function I_Has_Element (Self : Container; C : Cursor) return Standard.Boolean;
-- <<experimental>> <<extension>> function I_Get_Element (Self : Container; C : Cursor) return Element_Type;
-- This is only to simplify the iteration over the read data -- procedure On_Data_Available -- (Self : not null access Ref; -- The_Reader : in DataReader_Access is -- begin -- for E of Ref (The_Reader).{Read|Take|..} do -- Process (E.Data, E.Sample_Info); -- end loop; -- end; procedure Read
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_read</dref> procedure Read
(Self : not null access constant Ref;
Received_Data : in out Data_Sequences.Sequence;
Info_Seq : in out DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_read</dref> function Read
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Read -- <internal> -- Access a collection of data samples from the DDS_DataReader. -- This operation offers the same functionality and API as take except that the -- samples returned remain in the DDS_DataReader such that they can be retrieved -- again by means of a read or take operation. -- Please refer to the documentation of take for details on the number of samples -- returned within the received_data and info_seq as well as the order in which -- the samples appear in these sequences. -- The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. -- If the sample belongs to the most recent generation of the instance, -- it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. -- It will not affect the instance_state of the instance. -- Important: If the samples "returned" by this function are loaned from -- RTI Data Distribution Service (see take for more information on memory loaning), -- it is important that their contents not be changed. -- Because the memory in which the data is stored belongs to the middleware, -- any modifications made to the data will be seen the next time the same samples -- are read or taken; -- the samples will no longer reflect the state that was received from the network. -- </internal> procedure Take
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_take</dref> procedure Take
(Self : not null access constant Ref;
Received_Data : out Data_Sequences.Sequence;
Info_Seq : out DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_take</dref> function Take
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Take -- <internal> -- Access a collection of data-samples from the DataReader. -- The operation will return the list of samples received by the -- DataReader since the last DataReader.take operation that match the -- specified SampleStateMask, ViewStateMask and InstanceStateMask. -- This operation may fail with an exception if -- DataReaderResourceLimitsQosPolicy::max_outstanding_reads limit -- has been exceeded. -- The actual number of samples returned depends on the information that has -- been received by the middleware as well as the HistoryQosPolicy, -- ResourceLimitsQosPolicy, DataReaderResourceLimitsQosPolicy and the -- characteristics of the data-type that is associated with the DataReader: -- * In the case where the HistoryQosPolicy::kind is KEEP_LAST_HISTORY_QOS, -- the call will return at most HistoryQosPolicy::depth samples per instance. -- * The maximum number of samples returned is limited by -- ResourceLimitsQosPolicy::max_samples, and by -- DataReaderResourceLimitsQosPolicy::max_samples_per_read. -- * For multiple instances, the number of samples returned is additionally -- limited by the product -- (ResourceLimitsQosPolicy::max_samples_per_instance * -- ResourceLimitsQosPolicy::max_instances) -- * If DataReaderResourceLimitsQosPolicy::max_infos is limited, -- the number of samples returned may also be limited if insufficient -- SampleInfo resources are available. -- If the read or take succeeds and the number of samples returned has been -- limited (by means of a maximum limit, as listed above, or insufficient -- SampleInfo resources), -- the call will complete successfully and provide those samples the reader -- is able to return. The user may need to make additional calls, -- or return outstanding loaned buffers in the case of insuffificient resources, -- in order to access remaining samples. -- Note that in the case where the Topic associated with the DataReader -- is bound to a data-type that has no key definition, -- then there will be at most one instance in the DataReader. -- So the per-sample limits will apply. -- The act of taking a sample removes it from Data Distribution Service -- so it cannot be read or taken again. -- If the sample belongs to the most recent generation of the instance, -- it will also set the view_state of the sample's instance to NOT_NEW_VIEW_STATE. -- It will not affect the instance_state of the sample's instance. -- After DataReader.take completes, received_data and info_seq will be of -- the same length and contain the received data. -- If the sequences are empty (maximum size equal 0) when the take is called, -- the samples returned in the received_data and the corresponding -- info_seq are 'loaned' to the application from buffers provided by the DataReader. -- The application can use them as desired and has guaranteed exclusive access to them. -- Once the application completes its use of the samples it must 'return the loan' -- to the DataReader by calling the DataReader.return_loan operation. -- Note: -- While you must call Return_Loan at some point, you do not have to do so -- before the next take call. -- However, failure to return the loan will eventually deplete the DataReader -- of the buffers it needs to receive new samples and eventually samples will -- start to be lost. The total number of buffers available to the DataReader -- is specified by the ResourceLimitsQosPolicy and the DataReaderResourceLimitsQosPolicy. -- If the sequences are not empty (maximum size not equal 0) when the take is called, -- samples are copied to received_data and info_seq. The application will not -- need to call return_loan. -- The order of the samples returned to the caller depends on the PresentationQosPolicy. -- * If PresentationQosPolicy::access_scope is INSTANCE_PRESENTATION_QOS, -- the returned collection is a list where samples belonging to the -- same data instance are consecutive. -- * If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and -- PresentationQosPolicy::ordered_access is set to BOOLEAN_FALSE, -- then returned collection is a list where samples belonging to -- the same data instance are consecutive. -- * If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and -- PresentationQosPolicy::ordered_access is set to TRUE, then the -- returned collection is a list were the relative order of samples is -- preserved also accross different instances. Note that samples belonging -- to the same instance may or may not be consecutive. This is because -- to preserve order it may be necessary to mix samples from different instances. -- * If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and -- PresentationQosPolicy::ordered_access is set to FALSE, then returned -- collection is a list where samples belonging to the same data instance -- are consecutive. [Not supported (optional)] -- * If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and -- PresentationQosPolicy::ordered_access is set to TRUE, -- then the returned collection contains at most one sample. -- The difference in this case is due to the fact that is required that -- the application is able to read samples belonging to different DataReader -- objects in a specific order. [Not supported (optional)] -- In any case, the relative order between the samples of one instance is consistent -- with the DESTINATION_ORDER policy: -- * If DestinationOrderQosPolicy::kind is BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, -- samples belonging to the same instances will appear in the relative order -- in which there were received (FIFO, earlier samples ahead of the later samples). -- * If DestinationOrderQosPolicy::kind is BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, -- samples belonging to the same instances will appear in the relative order -- implied by the source_timestamp (FIFO, smaller values of source_timestamp -- ahead of the larger values). -- If the DataReader has no samples that meet the constraints, the function -- will fail with exception NO_DATA. -- In addition to the collection of samples, the read and take operations also -- use a collection of SampleInfo structures. -- SEQUENCES USAGE IN TAKE AND READ -- The initial (input) properties of the received_data and info_seq collections -- will determine the precise behavior of the read or take operation. -- For the purposes of this description, the collections are modeled as having -- these properties: -- * whether the collection container owns the memory of the elements -- within (owns, see Seq_has_ownership) -- * the current-length (len, see Seq_get_length) -- * the maximum length (max_len, see Seq_get_maximum) -- -- The initial values of the owns, len and max_len properties for the received_data -- and info_seq collections govern the behavior of the read and take operations -- as specified by the following rules : -- 1. The values of owns, len and max_len properties for the two collections must be identical. -- Otherwise read/take will fail with PRECONDITION_NOT_MET. -- 2. On successful output, the values of owns, len and max_len -- will be the same for both collections. -- 3. If the initial max_len==0, then the received_data and info_seq -- collections will be filled with elements that are loaned by the DataReader. -- On output, owns will be FALSE, len will be set to the number of values returned, -- and max_len will be set to a value verifying max_len >= len. -- The use of this variant allows for zero-copy access to the data and -- the application will need to return the loan to the DataWriter using return_loan. -- 4. If the initial max_len>0 and owns==FALSE, then the read or take operation -- will fail with exception PRECONDITION_NOT_MET. -- This avoids the potential hard-to-detect memory leaks caused by an -- application forgetting to return the loan. -- 5. If initial max_len>0 and owns==TRUE, then the read or take operation will copy -- the received_data values and SampleInfo values into the elements already -- inside the collections. On output, owns will be TRUE, len will be set to -- the number of values copied and max_len will remain unchanged. -- The use of this variant forces a copy but the application can control -- where the copy is placed and the application will not need to return the loan. -- The number of samples copied depends on the relative values of max_len and max_samples: -- * If max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. -- The use of this variant lets the application limit the number of samples -- returned to what the sequence can accommodate. -- * If max_samples <= max_len, then at most max_samples values will be copied. -- The use of this variant lets the application limit the number of samples -- returned to fewer that what the sequence can accommodate. -- * If max_samples > max_len, then the read or take operation will fail with -- exception PRECONDITION_NOT_MET. This avoids the potential confusion where -- the application expects to be able to access up to max_samples, but that -- number can never be returned, even if they are available in the DataReader, -- because the output sequence cannot accommodate them. -- As described above, upon completion, the received_data and info_seq collections -- may contain elements loaned from the DataReader. -- If this is the case, the application will need to use return_loan to return -- the loan once it is no longer using the received_data in the collection. -- When return_loan completes, the collection will have owns=FALSE and max_len=0. -- The application can determine whether it is necessary to return the loan or not -- based on how the state of the collections when the read/take operation was called -- or by accessing the owns property. However, in many cases it may be simpler to -- always call return_loan, as this operation is harmless -- (i.e., it leaves all elements unchanged) if the collection does not have a loan. -- To avoid potential memory leaks, the implementation of the data and SampleInfo -- collections should disallow changing the length of a collection for which owns==FALSE. -- Furthermore, deleting a collection for which owns==FALSE should be considered an error. -- On output, the collection of data values and the collection of SampleInfo structures -- are of the same length and are in a one-to-one correspondence. -- Each SampleInfo provides information, such as the source_timestamp, -- the sample_state, view_state, and instance_state, etc., about the corresponding sample. -- -- Some elements in the returned collection may not have valid data. -- If the instance_state in the SampleInfo is NOT_ALIVE_DISPOSED_INSTANCE_STATE -- or NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance -- in the collection (that is, the one whose SampleInfo has sample_rank==0) -- does not contain valid data. -- Samples that contain no data do not count towards the limits imposed by the -- ResourceLimitsQosPolicy. The act of reading/taking a sample sets its -- sample_state to READ_SAMPLE_STATE. -- If the sample belongs to the most recent generation of the instance, -- it will also set the view_state of the instance to NOT_NEW_VIEW_STATE. -- It will not affect the instance_state of the instance. -- This operation must be provided on the specialized class that is generated for -- the particular application data-type that is being read. If the DataReader has -- no samples that meet the constraints, the operations fails with exception NO_DATA. -- </internal> procedure Read_W_Condition
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Condition : access DDS.ReadCondition.Ref'Class);
-- <dref>FooDataReader_read_w_condition</dref> procedure Read_W_Condition
(Self : not null access constant Ref;
Received_Data : out Data_Sequences.Sequence;
Info_Seq : out DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Condition : access DDS.ReadCondition.Ref'Class);
-- <dref>FooDataReader_read_w_condition</dref> function Read_W_Condition
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Condition : access DDS.ReadCondition.Ref'Class) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Read_W_Condition -- <internal> -- Accesses via read the samples that match the criteria specified in the ReadCondition. -- This operation is especially useful in combination with QueryCondition to -- filter data samples based on the content. -- The specified ReadCondition must be attached to the DataReader; -- otherwise the operation will fail with exception PRECONDITION_NOT_MET. -- In case the ReadCondition is a plain ReadCondition and not the -- specialized QueryCondition, the operation is equivalent to calling read -- and passing as sample_states, view_states and instance_states the value of -- the corresponding attributes in the read_condition. -- Using this operation, the application can avoid repeating the same parameters -- specified when creating the ReadCondition. -- The samples are accessed with the same semantics as read. -- If the DataReader has no samples that meet the constraints, -- the operation will fail with exception RETCODE_NO_DATA. -- </internal> procedure Take_W_Condition
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Condition : access DDS.ReadCondition.Ref'Class);
-- <dref>FooDataReader_take_w_condition</dref> function Take_W_Condition
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Condition : access DDS.ReadCondition.Ref'Class) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Take_W_Condition -- <internal> -- Analogous to read_w_condition except it accesses samples via the take operation. -- This operation is analogous to read_w_condition except that it accesses -- samples via the take operation. -- The specified ReadCondition must be attached to the DataReader; -- otherwise the operation will fail with exception PRECONDITION_NOT_MET. -- The samples are accessed with the same semantics as take. -- This operation is especially useful in combination with QueryCondition -- to filter data samples based on the content. -- If the DataReader has no samples that meet the constraints, -- the function will fail with exception NO_DATA. -- </internal> procedure Read_Next_Sample
(Self : not null access constant Ref;
Received_Data : out Data_Type;
Sample_Info : not null access DDS.SampleInfo);
-- <dref>FooDataReader_read_next_sample</dref> procedure Read_Next_Sample
(Self : not null access constant Ref;
Received_Data : not null Data_Type_Access;
Sample_Info : not null access DDS.SampleInfo);
-- <dref>FooDataReader_read_next_sample</dref> -- <internal> -- Copies the next not-previously-accessed data value from the DataReader. -- This operation copies the next not-previously-accessed data value from the DataReader. -- This operation also copies the corresponding SampleInfo. The implied order among -- the samples stored in the DataReader is the same as for the read operation. -- The read_next_sample operation is semantically equivalent to the read operation, -- where the input data sequences has max_len=1, the sample_states=NOT_READ, -- the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. -- The read_next_sample operation provides a simplified API to 'read' samples, -- avoiding the need for the application to manage sequences and specify states. -- If there is no unread data in the DataReader, the operation will fail with -- exception NO_DATA and nothing is copied. -- </internal> procedure Take_Next_Sample
(Self : not null access constant Ref;
Received_Data : not null Data_Type_Access;
Sample_Info : not null access DDS.SampleInfo);
-- <dref>FooDataReader_take_next_sample</dref> procedure Take_Next_Sample
(Self : not null access constant Ref;
Received_Data : out Data_Type;
Sample_Info : not null access DDS.SampleInfo);
-- <dref>FooDataReader_take_next_sample</dref> -- <internal> -- Copies the next not-previously-accessed data value from the DataReader. -- This operation copies the next not-previously-accessed data value from the DataReader -- and 'removes' it from the DataReader so that it is no longer accessible. -- This operation also copies the corresponding SampleInfo. -- This operation is analogous to the read_next_sample except for the fact -- that the sample is removed from the DataReader. -- The take_next_sample operation is semantically equivalent to the take operation, -- where the input data sequences has max_len=1, the sample_states=NOT_READ, -- the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. -- The read_next_sample operation provides a simplified API to 'take' samples, -- avoiding the need for the application to manage sequences and specify states. -- If tere is no unread data in the DataReader, the operation will fail -- with exception NO_DATA and nothing is copied. -- </internal> procedure Read_Instance
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
A_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_read_instance</dref> function Read_Instance
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
A_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Read_Instance -- <internal> -- Access a collection of data samples from the DataReader. -- This operation accesses a collection of data values from the DataReader. -- The behavior is identical to read, except that all samples returned belong -- to the single specified instance whose handle is a_handle. -- Upon successful completion, the data collection will contain samples all -- belonging to the same instance. The corresponding SampleInfo verifies -- SampleInfo::instance_handle == a_handle. -- The read_instance operation is semantically equivalent to the read operation, -- except in building the collection, the DataReader will check that the sample -- belongs to the specified instance and otherwise it will not place the sample -- in the returned collection. -- The behavior of the read_instance operation follows the same rules as the -- read operation regarding the pre-conditions and post-conditions for the received_data -- and sample_info. Similar to the read, the read_instance operation may 'loan' elements -- to the output collections, which must then be returned by means of return_loan. -- Similar to the read, this operation must be provided on the specialized class that -- is generated for the particular application data-type that is being taken. -- If the DataReader has no samples that meet the constraints, -- the function will fail with RETCODE_NO_DATA. -- This operation may fail with RETCODE_BAD_PARAMETER if the InstanceHandle_t -- a_handle does not correspond to an existing data-object known to the DataReader. -- </internal> procedure Take_Instance
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
A_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_take_instance</dref> function Take_Instance
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
A_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Take_Instance -- <internal> -- Access a collection of data samples from the DataReader. -- This operation accesses a collection of data values from the DataReader. -- The behavior is identical to take, except for that all samples returned belong -- to the single specified instance whose handle is a_handle. -- The semantics are the same for the take operation, except in building the collection, -- the DataReader will check that the sample belongs to the specified instance, -- and otherwise it will not place the sample in the returned collection. -- The behavior of the take_instance operation follows the same rules as the -- read operation regarding the pre-conditions and post-conditions for the -- received_data and sample_info. Similar to the read, the take_instance operation may -- 'loan' elements to the output collections, which must then be returned by means of return_loan. -- Similar to the read, this operation must be provided on the specialized class -- that is generated for the particular application data-type that is being taken. -- If the DataReader has no samples that meet the constraints, the function fails with exception NO_DATA. -- This operation may fail with exception BAD_PARAMETER if the InstanceHandle_t -- a_handle does not correspond to an existing data-object known to the DataReader. -- </internal> procedure Read_Next_Instance
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_read_next_instance</dref> function Read_Next_Instance
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Read_Next_Instance -- <internal> -- Access a collection of data samples from the DataReader. -- This operation accesses a collection of data values from the DataReader -- where all the samples belong to a single instance. The behavior is similar to -- read_instance, except that the actual instance is not directly specified. -- Rather, the samples will all belong to the 'next' instance with instance_handle -- 'greater' than the specified 'previous_handle' that has available samples. -- This operation implies the existence of a total order 'greater-than' relationship -- between the instance handles. The specifics of this relationship are not all -- important and are implementation specific. The important thing is that, -- according to the middleware, all instances are ordered relative to each other. -- This ordering is between the instance handles; It should not depend on the state -- of the instance (e.g. whether it has data or not) and must be defined even for -- instance handles that do not correspond to instances currently managed by the DataReader. -- For the purposes of the ordering, it should be 'as if' each instance handle was -- represented as unique integer. -- The behavior of read_next_instance is 'as if' the DataReader invoked read_instance, -- passing the smallest instance_handle among all the ones that: -- (a) are greater than previous_handle, and -- (b) have available samples (i.e. samples that meet the constraints imposed by the specified states). -- The special value HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. -- So the use of the parameter value previous_handle == HANDLE_NIL will -- return the samples for the instance which has the smallest instance_handle -- among all the instances that contain available samples. -- The operation read_next_instance is intended to be used in an -- application-driven iteration, where the application starts by passing -- previous_handle == HANDLE_NIL, examines the samples returned, and then uses -- the instance_handle returned in the SampleInfo as the value of the previous_handle -- argument to the next call to read_next_instance. The iteration continues -- until read_next_instance fails with the value exception NO_DATA. -- Note that it is possible to call the read_next_instance operation with a -- previous_handle that does not correspond to an instance currently managed by -- the DataReader. This is because as stated earlier the 'greater-than' relationship -- is defined even for handles not managed by the DataReader. -- One practical situation where this may occur is when an application is iterating -- though all the instances, takes all the samples of a NOT_ALIVE_NO_WRITERS_INSTANCE_STATE -- instance, returns the loan (at which point the instance information may be removed, -- and thus the handle becomes invalid), and tries to read the next instance. -- The behavior of the read_next_instance operation follows the same rules as -- the read operation regarding the pre-conditions and post-conditions for the -- received_data and sample_info. Similar to the read, the read_instance operation may -- 'loan' elements to the output collections, which must then be returned by means of return_loan. -- Similar to the read, this operation must be provided on the specialized class -- that is generated for the particular application data-type that is being taken. -- If the DataReader has no samples that meet the constraints, the function -- will fail with exception NO_DATA. -- </internal> procedure Take_Next_Instance
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE);
-- <dref>FooDataReader_take_next_instance</dref> function Take_Next_Instance
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Sample_States : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE;
View_States : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE;
Instance_States : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Take_Next_Instance -- <internal> -- Access a collection of data samples from the DataReader. -- This operation accesses a collection of data values from the DataReader and -- 'removes' them from the DataReader. -- This operation has the same behavior as read_next_Ret.Received_Datainstance, except that the -- samples are 'taken' from the DataReader such that they are no longer accessible -- via subsequent 'read' or 'take' operations. -- Similar to the operation read_next_instance, it is possible to call take_next_instance -- with a previous_handle that does not correspond to an instance currently managed by the DataReader. -- The behavior of the take_next_instance operation follows the same rules as the -- read operation regarding the pre-conditions and post-conditions for the received_data -- and sample_info. Similar to the read, the take_next_instance operation may 'loan' -- elements to the output collections, which must then be returned by means of return_loan. -- Similar to the read, this operation must be provided on the specialized class that -- is generated for the particular application data-type that is being taken. -- If the DataReader has no samples that meet the constraints, -- the function will fail with exception NO_DATA. -- </internal> procedure Read_Next_Instance_W_Condition
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access);
-- <dref>FooDataReader_read_next_instance_w_condition</dref> function Read_Next_Instance_W_Condition
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Read_Next_Instance_W_Condition -- <internal> -- Accesses via read_next_instance the samples that match the criteria -- specified in the ReadCondition. -- This operation access a collection of data values from the DataReader. -- The behavior is identical to read_next_instance, except that all samples returned satisfy -- the specified condition. In other words, on success, all returned samples -- belong to the same instance, and the instance is the instance with 'smallest' -- instance_handle among the ones that verify: -- (a) instance_handle >= previous_handle, and -- (b) have samples for which the specified ReadCondition evaluates to TRUE. -- Similar to the operation read_next_instance, it is possible to call -- read_next_instance_w_condition with a previous_handle that does not correspond -- to an instance currently managed by the DataReader. -- The behavior of the read_next_instance_w_condition operation follows the same -- rules as the read operation regarding the pre-conditions and post-conditions for -- the received_data and sample_info. Similar to the read, the -- read_next_instance_w_condition operation may 'loan' elements to the output collections, -- which must then be returned by means of return_loan. -- Similar to the read, this operation must be provided on the specialized class that -- is generated for the particular application data-type that is being taken. -- If the DataReader has no samples that meet the constraints, -- the function will fail with exception NO_DATA. -- </internal> procedure Read_Instance_W_Condition
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
A_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access);
-- <dref>FooDataReader_read_instance_w_condition</dref> procedure Take_Instance_W_Condition
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
A_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access);
-- <dref>FooDataReader_take_instance_w_condition</dref> procedure Take_Next_Instance_W_Condition
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access);
-- <dref>FooDataReader_take_next_instance_w_condition</dref> procedure Take_Next_Instance_W_Condition
(Self : not null access constant Ref;
Received_Data : in out Data_Sequences.Sequence;
Info_Seq : in out DDS.SampleInfo_Seq.Sequence;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access);
-- <dref>FooDataReader_take_next_instance_w_condition</dref> function Take_Next_Instance_W_Condition
(Self : not null access Ref;
Max_Samples : in DDS.Long := DDS.LENGTH_UNLIMITED;
Previous_Handle : access constant DDS.InstanceHandle_T;
Condition : DDS.ReadCondition.Ref_Access) return Container'Class;
-- <<experimental>> <<extension>> Returns a container which allows for easier iteration through -- samples. See procedure Take_Next_Instance_W_Condition -- <internal> -- Accesses via take_next_instance the samples that match the criteria specified -- in the ReadCondition. -- This operation access a collection of data values from the DataReader and -- 'removes' them from the DataReader. -- The operation has the same behavior as read_next_instance_w_condition, except -- that the samples are 'taken' from the DataReader such that they are no longer -- accessible via subsequent 'read' or 'take' operations. -- Similar to the operation read_next_instance, it is possible to call -- take_next_instance_w_condition with a previous_handle that does not correspond -- to an instance currently managed by the DataReader. -- The behavior of the take_next_instance_w_condition operation follows the same -- rules as the read operation regarding the pre-conditions and post-conditions -- for the received_data and sample_info. Similar to the read, -- the take_next_instance_w_condition operation may 'loan' elements to the output -- collections, which must then be returned by means of return_loan. -- Similar to the read, this operation must be provided on the specialized class -- that is generated for the particular application data-type that is being taken. -- If the DataReader has no samples that meet the constraints, -- the function will fail with exception NO_DATA. -- </internal> procedure Return_Loan
(Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence);
-- <dref>FooDataReader_return_loan</dref> procedure Return_Loan
(Self : not null access constant Ref;
Received_Data : in out Data_Sequences.Sequence;
Info_Seq : in out DDS.SampleInfo_Seq.Sequence);
-- <dref>FooDataReader_return_loan</dref> -- <internal> -- Indicates to the DataReader that the application is done accessing the collection -- of received_data and info_seq obtained by some earlier invocation of -- read or take on the DataReader. -- This operation indicates to the DataReader that the application is done accessing -- the collection of received_data and info_seq obtained by some earlier -- invocation of read or take on the DataReader. -- The received_data and info_seq must belong to a single related "pair"; that is, -- they should correspond to a pair returned from a single call to read or take. -- The received_data and info_seq must also have been obtained from the same DataReader -- to which they are returned. If either of these conditions is not met, the operation -- will fail with exception PRECONDITION_NOT_MET. -- The operation return_loan allows implementations of the read and take operations -- to "loan" buffers from the DataReader to the application and in this manner provide -- "zerocopy" access to the data. During the loan, the DataReader will guarantee -- that the data and sample-information are not modified. -- It is not necessary for an application to return the loans immediately after -- the read or take calls. However, as these buffers correspond to internal resources -- inside the DataReader, the application should not retain them indefinitely. -- The use of return_loan is only necessary if the read or take calls "loaned" -- buffers to the application. This only occurs if the received_data and info_Seq -- collections had max_len=0 at the time read or take was called. -- The application may also examine the "owns" property of the collection to determine -- where there is an outstanding loan. However, calling return_loan on a collection -- that does not have a loan is safe and has no side effects. -- If the collections had a loan, upon completion of return_loan, -- the collections will have max_len=0. -- Similar to read, this operation must be provided on the specialized class that -- is generated for the particular application data-type that is being taken. -- </internal> procedure Get_Key_Value
(Self : not null access constant Ref;
Key_Holder : not null Data_Type_Access;
Handle : access constant DDS.InstanceHandle_T);
-- <dref>FooDataReader_get_key_value</dref> procedure Get_Key_Value
(Self : not null access constant Ref;
Key_Holder : out Data_Type;
Handle : access constant DDS.InstanceHandle_T);
-- <dref>FooDataReader_get_key_value</dref> procedure Get_Key_Value
(Self : not null access constant Ref;
Key_Holder : out Data_Type;
Handle : in DDS.InstanceHandle_T);
-- <dref>FooDataReader_get_key_value</dref> -- <internal> -- Retrieve the instance key that corresponds to an instance handle. -- Useful for keyed data types. -- The operation will only fill the fields that form the key inside the key_holder instance. -- For keyed data types, this operation may fail with exception BAD_PARAMETER -- if the handle does not correspond to an existing data-object known to the DDS_DataReader. -- </internal> function Lookup_Instance
(Self : not null access constant Ref;
Key_Holder : not null Data_Type_Access) return DDS.InstanceHandle_T;
-- <dref>FooDataReader_lookup_instance</dref> function Lookup_Instance
(Self : not null access constant Ref;
Key_Holder : Data_Type) return DDS.InstanceHandle_T;
-- <dref>FooDataReader_lookup_instance</dref> procedure Lookup_Instance
(Self : not null access constant Ref;
Key_Holder : Data_Type;
Instance : out DDS.InstanceHandle_T);
-- <dref>FooDataReader_lookup_instance</dref> -- <internal> -- Retrieve the instance handle that corresponds to an instance key_holder. -- Useful for keyed data types. -- This operation takes as a parameter an instance and returns a handle that -- can be used in subsequent operations that accept an instance handle as an argument. -- The instance parameter is only used for the purpose of examining the fields that -- define the key. This operation does not register the instance in question. -- If the instance has not been previously registered, or if for any other reason -- the Service is unable to provide an instance handle, -- the Service will return the special value HANDLE_NIL -- </internal> function Is_Data_Consistent
(Self : not null access Ref;
Sample : in not null Data_Type_Access;
Sample_Info : in not null DDS.SampleInfo_Access) return Standard.Boolean;
-- <dref>FooDataReader_is_data_consistent</dref> -- <internal> -- When using SHMEM_REF transfer mode, the DataWriter will pass a reference -- to the sample on shared memory to the DataReader. The DataReader will -- use this reference to pass sample data up to the application in the form -- of a loaned sample that's actually stored in the DataWriter's queue in -- shared memory. -- In many situations, sample memory may be reused by the DataWriter to -- send another sample before or while the subscribing application acceses -- sample data, creating a data inconsistency problem. -- Is_Data_Consistent can be used to detect these inconsistencies. It -- should be used *after* the sample has been processed. If it returns -- false, processed data should be discarded. -- If Is_Data_Consistent is only called before processing data, it could -- return true at that point but the sample could still be modified while -- being processed, leading to a race condition. -- </internal> function As_DataReader (Self : Ref_Access) return Standard.DDS.DataReader.Ref_Access is
(Standard.DDS.DataReader.Ref_Access (Self));
function Narrow
(Self : access DDS.DataReader.Ref'Class) return not null access Ref is
(Ref (Self.all)'Access);
function CreateTypedI return DDS.DataReader.Ref_Access;
procedure DestroyTypedI
(Reader : in out DDS.DataReader.Ref_Access);
private procedure read_or_takeI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; sample_states : DDS.SampleStateMask; view_states : DDS.ViewStateMask; instance_states : DDS.InstanceStateMask; take : DDS.Boolean); function read_or_takeI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; sample_states : DDS.SampleStateMask; view_states : DDS.ViewStateMask; instance_states : DDS.InstanceStateMask; take : DDS.Boolean) return DDS_ReturnCode_t;
procedure read_or_take_w_conditionI (Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_samples : DDS.Long; Condition : not null access constant DDS.ReadCondition.Ref'Class;
Take : DDS.Boolean); function read_or_take_w_conditionI (Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_samples : DDS.Long; Condition : not null access constant DDS.ReadCondition.Ref'Class;
Take : DDS.Boolean) return DDS_ReturnCode_t;
procedure read_or_take_next_sampleI (self : not null access constant Ref;
Received_Data : not null Data_Type_Access;
sample_info : not null access DDS.SampleInfo;
take : DDS.Boolean); procedure read_or_take_instanceI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; handle : not null access constant DDS.InstanceHandle_T;
sample_states : DDS.SampleStateMask; view_states : DDS.ViewStateMask; instance_states : DDS.InstanceStateMask; take : DDS.Boolean); function read_or_take_instanceI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; handle : not null access constant DDS.InstanceHandle_T;
sample_states : DDS.SampleStateMask; view_states : DDS.ViewStateMask; instance_states : DDS.InstanceStateMask; take : DDS.Boolean) return DDS_ReturnCode_t;
procedure read_or_take_next_instanceI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; previous_handle : not null access constant DDS.InstanceHandle_T;
sample_states : DDS.SampleStateMask; view_states : DDS.ViewStateMask; instance_states : DDS.InstanceStateMask; Take : DDS.Boolean); function read_or_take_next_instanceI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; previous_handle : not null access constant DDS.InstanceHandle_T;
sample_states : DDS.SampleStateMask; view_states : DDS.ViewStateMask; instance_states : DDS.InstanceStateMask; Take : DDS.Boolean) return DDS_ReturnCode_t;
procedure Read_Or_Take_Instance_W_ConditionI (Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : DDS.Long; Handle : not null access constant DDS.InstanceHandle_T;
Condition : not null access constant DDS.ReadCondition.Ref'Class;
Take : DDS.Boolean); function Read_Or_Take_Instance_W_ConditionI (Self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
Max_Samples : DDS.Long; Handle : not null access constant DDS.InstanceHandle_T;
Condition : not null access constant DDS.ReadCondition.Ref'Class;
Take : DDS.Boolean) return DDS_ReturnCode_t;
procedure read_or_take_next_instance_w_conditionI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; previous_handle : not null access constant DDS.InstanceHandle_T;
condition : not null access constant DDS.ReadCondition.Ref'Class;
take : DDS.Boolean); function read_or_take_next_instance_w_conditionI (self : not null access constant Ref;
Received_Data : not null access Data_Sequences.Sequence;
Info_Seq : not null access DDS.SampleInfo_Seq.Sequence;
max_samples : DDS.Long; previous_handle : not null access constant DDS.InstanceHandle_T;
condition : not null access constant DDS.ReadCondition.Ref'Class;
take : DDS.Boolean) return DDS_ReturnCode_t;
-- type DDS_InstanceHandle_T_Access is access all DDS_InstanceHandle_t; -- function Convert_Handle is new Ada.Unchecked_Conversion (DDS.InstanceHandle_T_Access, DDS_InstanceHandle_T_Access); -- -- type DDS_SampleInfoSeq_Access is access all DDS_SampleInfoSeq; -- function Convert_SampleInfoSeq is new Ada.Unchecked_Conversion (SampleInfo_Seq.Sequence_Access, DDS_SampleInfoSeq_Access); -- -- type DDS_SampleInfo_Access is access all DDS_SampleInfo; -- function Convert_SampleInfo is new Ada.Unchecked_Conversion (DDS.SampleInfo_Access, DDS_SampleInfo_Access); type Container is limited new Ada.Finalization.Limited_Controlled with record
Received_Data : aliased Data_Sequences.Sequence;
Info_Seq : aliased DDS.SampleInfo_Seq.Sequence;
Reader : Ref_Access; Retcode : DDS_ReturnCode_t := DDS_RETCODE_NO_DATA;
end record;
procedure Finalize (Self : in out Container);
end DDS.Typed_DataReader_Generic;