-- (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. with DDS.DataWriter; with DDS.DataWriter_Impl; with DDS.Treats_Generic; generic with package Treats is new DDS.Treats_Generic (<>);
use Treats;
package DDS.Typed_DataWriter_Generic is
pragma Suppress (Elaboration_Check); type Ref is new Standard.DDS.DataWriter_Impl.Ref with null record;
type Ref_Access is access all Ref'Class;
function Register_Instance
(Self : not null access Ref;
Instance_Data : Data_Type)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance</dref> function Register_Instance
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance</dref> -- <internal> -- Informs Data Distribution Service that the application will be modifying a -- particular instance. -- This operation is only useful for keyed data types. Using it for non-keyed -- types causes no effect and returns HANDLE_NIL. The operation takes as a parameter -- an instance (of which only the key value is examined) and returns a handle that -- can be used in successive write() or dispose() operations. -- The operation gives Data Distribution Service an opportunity to pre-configure -- itself to improve performance. -- The use of this operation by an application is optional even for keyed types. -- If an instance has not been pre-registered, the application can use the special -- value HANDLE_NIL as the InstanceHandle_t paramater to the write or dispose -- operation and Data Distribution Service will auto-register the instance. -- For best performance, the operation should be invoked prior to calling any -- operation that modifies the instance, such as write, write_w_timestamp, -- dispose and dispose_w_timestamp and the handle used in conjunction with -- the data for those calls. -- When this operation is used, Data Distribution Service will automatically supply -- the value of the source_timestamp that is used. -- This operation may fail and return HANDLE_NIL if ResourceLimitsQosPolicy::max_instances -- limit has been exceeded. -- The operation is idempotent. If it is called for an already registered instance, -- it just returns the already allocated handle. This may be used to lookup and retrieve -- the handle allocated to a given instance. -- This operation can only be called after DataWriter has been enabled. -- Otherwise, HANDLE_NIL will be returned. -- </internal> function Register_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Source_Timestamp : in Standard.DDS.Time_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_timestamp</dref> function Register_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Source_Timestamp : in Standard.DDS.Time_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_timestamp</dref> -- <internal> -- Performs the same functions as register_instance except that the application -- provides the value for the source_timestamp. -- The provided source_timestamp potentially affects the relative order in which -- readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details. -- This operation may fail and return DDS_HANDLE_NIL if ResourceLimitsQosPolicy::max_instances -- limit has been exceeded. -- This operation can only be called after DataWriter has been enabled. -- Otherwise, HANDLE_NIL will be returned. -- </internal> function Register_Instance_W_Params
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Params : not null access DDS.WriteParams_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_params</dref> function Register_Instance_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type;
Params : not null access DDS.WriteParams_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_params</dref> -- <internal> -- Performs the same functions as register_instance except that ... -- readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details. -- This operation may fail and return DDS_HANDLE_NIL if ResourceLimitsQosPolicy::max_instances -- limit has been exceeded. -- This operation can only be called after DataWriter has been enabled. -- Otherwise, HANDLE_NIL will be returned. -- </internal> procedure Unregister_Instance
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_unregister_instance</dref> procedure Unregister_Instance
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_unregister_instance</dref> -- <internal> -- Reverses the action of register_instance. -- This operation is useful only for keyed data types. Using it for non-keyed types -- causes no effect and reports no error. The operation takes as a parameter an -- instance (of which only the key value is examined) and a handle. -- This operation should only be called on an instance that is currently registered. -- This includes instances that have been auto-registered by calling operations such -- as write or dispose as described in register_instance. Otherwise, this operation may -- fail with exception BAD_PARAMETER. -- This only need be called just once per instance, regardless of how many times -- register_instance was called for that instance. -- When this operation is used, DDS will automatically supply -- the value of the source_timestamp that is used. -- This operation informs DDS that the DataWriter is no longer -- going to provide any information about the instance. This operation also indicates -- that DDS can locally remove all information regarding that instance. -- The application should not attempt to use the handle previously allocated to -- that instance after calling unregister_instance(). -- The special value HANDLE_NIL can be used for the parameter handle. -- This indicates that the identity of the instance should be automatically deduced -- from the instance_data (by means of the key). -- If handle is any value other than HANDLE_NIL, then it must correspond to an instance -- that has been registered. If there is no correspondence, the operation will fail with -- exception BAD_PARAMETER. -- DDS will not detect the error when the handle is any value other than HANDLE_NIL, -- corresponds to an instance that has been registered, but does not correspond to the -- instance deduced from the instance_data (by means of the key). DDS will treat as if -- the unregister_instance() operation is for the instance as indicated by the handle. -- If after a unregister_instance, the application wants to modify (write or dispose) -- an instance, it has to register it again, or else use the special handle value HANDLE_NIL. -- This operation does not indicate that the instance is deleted -- (that is the purpose of dispose). The operation unregister_instance just indicates -- that the DataWriter no longer has anything to say about the instance. DataReader -- entities that are reading the instance may receive a sample with -- NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other -- DataWriter objects writing that same instance. -- This operation can affect the ownership of the data instance (see OWNERSHIP). -- If the DataWriter was the exclusive owner of the instance, then calling -- unregister_instance() will relinquish that ownership. -- If ReliabilityQosPolicy::kind is set to RELIABLE_RELIABILITY_QOS and the unregistration -- would overflow the resource limits of this writer or of a reader, this operation -- may block for up to ReliabilityQosPolicy::max_blocking_time; if this writer is -- still unable to unregister after that period, this function will fail with exception TIMEOUT. -- </internal> procedure Unregister_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_unregister_instance_w_timestamp</dref> procedure Unregister_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_unregister_instance_w_timestamp</dref> -- <internal> -- Performs the same function as unregister_instance except that it also provides -- the value for the source_timestamp. -- The provided source_timestamp potentially affects the relative order in which -- readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details. -- The constraints on the values of the handle parameter and the corresponding error -- behavior are the same specified for the unregister_instance operation. -- This operation may block and may time out (exception RETCODE_TIMEOUT) under -- the same circumtances described for the unregister_instance operation. -- </internal> procedure Unregister_Instance_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type;
Params : access DDS.WriteParams_T);
-- <dref>FooDataWriter_unregister_instance_w_params</dref> procedure Unregister_Instance_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Params : access DDS.WriteParams_T);
-- <dref>FooDataWriter_unregister_instance_w_params</dref> procedure Write
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T_Access);
-- <dref>FooDataWriter_write</dref> procedure Write
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_write</dref> procedure Write
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T_Access);
-- <dref>FooDataWriter_write</dref> procedure Write
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_write</dref> -- <internal> -- Modifies the value of a data instance. -- When this operation is used, DDS will automatically supply the value of the -- source_timestamp that is made available to DataReader objects by means of the -- source_timestamp attribute inside the SampleInfo. -- (Refer to SampleInfo and DESTINATION_ORDER QoS policy for details). -- As a side effect, this operation asserts liveliness on the DataWriter itself, -- the Publisher and the DomainParticipant. -- Note that the special value HANDLE_NIL can be used for the parameter handle. -- This indicates the identity of the instance should be automatically deduced -- from the instance_data (by means of the key). -- If handle is any value other than HANDLE_NIL, then it must correspond to an instance -- that has been registered. If there is no correspondence, the operation will fail -- with exception BAD_PARAMETER. -- DDS will not detect the error when the handle is any value other than HANDLE_NIL, -- corresponds to an instance that has been registered, but does not correspond -- to the instance deduced from the instance_data (by means of the key). -- DDS will treat as if the write() operation is for the instance as indicated by the handle. -- This operation may block if the RELIABILITY kind is set to RELIABLE_RELIABILITY_QOS -- and the modification would cause data to be lost or else cause one of the limits -- specified in the RESOURCE_LIMITS to be exceeded. -- Specifically, this operation may block in the following situations -- (note that the list may not be exhaustive), -- even if its HistoryQosPolicyKind is KEEP_LAST_HISTORY_QOS: -- * If (ResourceLimitsQosPolicy::max_samples < -- ResourceLimitsQosPolicy::max_instances * HistoryQosPolicy::depth), -- then in the situation where the max_samples resource limit is exhausted, -- DDS is allowed to discard samples of some other instance, as long as at -- least one sample remains for such an instance. If it is still not possible -- to make space available to store the modification, the writer is allowed to block. -- * If (ResourceLimitsQosPolicy::max_samples < ResourceLimitsQosPolicy::max_instances), -- then the DataWriter may block regardless of the HistoryQosPolicy::depth. -- This operation may also block when using BEST_EFFORT_RELIABILITY_QOS and -- ASYNCHRONOUS_PUBLISH_MODE_QOS. In this case, the DataWriter will queue samples -- until they are sent by the asynchronous publishing thread. -- The number of samples that can be stored is determined by the HistoryQosPolicy. -- If the asynchronous thread does not send samples fast enough -- (e.g., when using a slow FlowController), the queue may fill up. In that case, -- subsequent write calls will block. -- If this operation does block for any of the above reasons, the RELIABILITY -- max_blocking_time configures the maximum time the write operation may block -- (waiting for space to become available). If max_blocking_time elapses before -- the DataWriter is able to store the modification without exceeding the limits, -- the operation will time out (exception TIMEOUT). -- If there are no instance resources left, this operation may fail with exception -- OUT_OF_RESOURCES. Calling DataWriter.unregister_instance may help -- freeing up some resources. -- </internal> procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : not null Standard.DDS.InstanceHandle_T_Access;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref> procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Handle : not null Standard.DDS.InstanceHandle_T_Access;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref> procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref> procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref> -- <internal> -- Performs the same function as write except that it also provides the value -- for the source_timestamp. -- Explicitly provides the timestamp that will be available to the DataReader objects -- by means of the source_timestamp attribute inside the SampleInfo. -- (Refer to SampleInfo and DESTINATION_ORDER QoS policy for details) -- The constraints on the values of the handle parameter and the corresponding -- error behavior are the same specified for the write operation. -- This operation may block and time out (exception TIMEOUT) -- under the same circumtances described for write. -- If there are no instance resources left, this operation may fail with -- exception OUT_OF_RESOURCES. Calling unregister_instance may help free up some resources. -- This operation may fail with exception BAD_PARAMETER under the same circumstances -- described for the write operation. -- </internal> procedure Write_W_Params (Self : not null access Ref;
Instance_Data : Data_Type;
Params : in DDS.WriteParams_T);
-- <dref>FooDataWriter_write_w_params</dref> procedure Write_W_Params (Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Params : in DDS.WriteParams_T);
-- <dref>FooDataWriter_write_w_params</dref> -- <internal> -- Performs the same function as write and write_w_timestamp except -- that it also provides the values contained in params. -- -- Allows provision of the instance handle, source timestamp, publication priority, -- and cookie, in params. Allows provision of the sample identity, instance handle, source timestamp, -- The constraints on the values of the handle parameter and the corresponding error -- behavior are the same specified for the write operation. -- -- The cookie is a sequence of bytes tagging the data being written, -- and is used to retrieve the data when it is not available to the writer when needed. -- -- This operation may block and time out (DDS_RETCODE_TIMEOUT) under -- the same circumtances described for write. -- -- If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. -- Calling unregister_instance_w_params may help free up some resources. -- -- The handle is either returned by a previous call to DataWriter_register_instance, -- or else the special value DDS_HANDLE_NIL. If Foo has a key and handle is not DDS_HANDLE_NIL, -- handle must represent a registered instance of type Foo. Otherwise, -- this function may fail with DDS_RETCODE_BAD_PARAMETER. -- The source_timestamp value must be greater than or equal to the timestamp -- value used in the last writer operation -- (used in a register, unregister, dispose, or write, with either the -- automatically supplied timestamp or the application provided timestamp). -- This timestamp may potentially affect the order in which readers observe -- events from multiple writers. This timestamp will be available to the -- DDS.DataReader objects by means of the source_timestamp attribute -- inside the DDS.SampleInfo. -- </internal> procedure Dispose
(Self : not null access Ref;
Instance_Data : Data_Type;
Instance_Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_dispose</dref> procedure Dispose
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Instance_Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_dispose</dref> -- <internal> -- Requests the middleware to delete the data. -- This operation is useful only for keyed data types. Using it for non-keyed types -- has no effect and reports no error. -- The actual deletion is postponed until there is no more use for that data in the whole system. -- Applications are made aware of the deletion by means of operations on the DataReader -- objects that already knew that instance. DataReader objects that didn't know -- the instance will never see it. -- This operation does not modify the value of the instance. -- The instance_data parameter is passed just for the purposes of identifying the instance. -- When this operation is used, DDS will automatically -- supply the value of the source_timestamp that is made available to DataReader -- objects by means of the source_timestamp attribute inside the SampleInfo. -- The constraints on the values of the handle parameter and the corresponding -- error behavior are the same specified for the DataWriter.unregister_instance operation. -- The special value HANDLE_NIL can be used for the parameter instance_handle. -- This indicates the identity of the instance should be automatically deduced -- from the instance_data (by means of the key). -- If handle is any value other than HANDLE_NIL, then it must correspond to an -- instance that has been registered. If there is no correspondence, the operation -- will fail with exception BAD_PARAMETER. -- DDS will not detect the error when the handle is any -- value other than HANDLE_NIL, corresponds to an instance that has been registered, -- but does not correspond to the instance deduced from the instance_data (by means of the key). -- DDS will treat as if the dispose() operation is for the instance as indicated by the handle. -- This operation may block and time out (exception TIMEOUT) under the same -- circumtances described for write(). -- If there are no instance resources left, this operation may fail with exception OUT_OF_RESOURCES. -- Calling unregister_instance may help freeing up some resources. -- </internal> procedure Dispose_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Instance_Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_dispose_w_timestamp</dref> procedure Dispose_W_Timestamp
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Instance_Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_dispose_w_timestamp</dref> -- <internal> -- Performs the same functions as dispose except that the application provides -- the value for the source_timestamp that is made available to DataReader objects -- by means of the source_timestamp attribute inside the SampleInfo. -- The constraints on the values of the handle parameter and the corresponding -- error behavior are the same specified for the dispose operation. -- This operation may block and time out (exception TIMEOUT) under the same -- circumtances described for write. -- If there are no instance resources left, this operation may fail -- with exception OUT_OF_RESOURCES. -- Calling unregister_instance may help freeing up some resources. -- </internal> procedure Dispose_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type;
Params : in DDS.WriteParams_T);
-- <dref>FooDataWriter_dispose_w_params</dref> procedure Dispose_W_Params
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Params : in DDS.WriteParams_T);
-- <dref>FooDataWriter_dispose_w_params</dref> procedure Get_Key_Value
(Self : not null access Ref;
Key_Holder : out Data_Type;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_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. -- If the data has no key, this function has no effect and exit with no error. -- 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 DataWriter. -- </internal> procedure Get_Key_Value
(Self : not null access Ref;
Key_Holder : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_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. -- If the data has no key, this function has no effect and exit with no error. -- 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 DataWriter. -- </internal> function Lookup_Instance
(Self : not null access Ref;
Key_Holder : Data_Type) return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_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 -- DDS is unable to provide an instance handle, DDS will return the special value HANDLE_NIL. -- </internal> function Lookup_Instance
(Self : not null access Ref;
Key_Holder : not null Data_Type_Access) return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_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 -- DDS is unable to provide an instance handle, DDS will return the special value HANDLE_NIL. -- </internal> function As_DataWriter (Self : Ref_Access) return Standard.DDS.DataWriter.Ref_Access is
(Standard.DDS.DataWriter.Ref_Access (Self));
function Narrow
(Self : access DDS.DataWriter.Ref'Class) return not null access Ref is
(if Self = null then null else Ref (Self.all)'Access);
function CreateTypedI return Standard.DDS.DataWriter.Ref_Access;
procedure DestroyTypedI
(Writer : in out Standard.DDS.DataWriter.Ref_Access);
end DDS.Typed_DataWriter_Generic;