RTI Connext Traditional C++ API Version 7.1.0
FooDataWriter Class Referenceabstract

<<interface>> <<generic>> User data type specific data writer. More...

Inheritance diagram for FooDataWriter:
DDSDataWriter DDSDomainEntity DDSEntity

Public Member Functions

virtual DDS_InstanceHandle_t register_instance (const Foo &instance_data)=0
 Informs RTI Connext that the application will be modifying a particular instance. More...
 
virtual DDS_InstanceHandle_t register_instance_w_timestamp (const Foo &instance_data, const DDS_Time_t &source_timestamp)=0
 Performs the same functions as register_instance except that the application provides the value for the source_timestamp. More...
 
virtual DDS_InstanceHandle_t register_instance_w_params (const Foo &instance_data, DDS_WriteParams_t &params)=0
 Performs the same function as FooDataWriter::register_instance and FooDataWriter::register_instance_w_timestamp except that it also provides the values contained in params. More...
 
virtual DDS_ReturnCode_t unregister_instance (const Foo &instance_data, const DDS_InstanceHandle_t &handle)=0
 Reverses the action of FooDataWriter::register_instance. More...
 
virtual DDS_ReturnCode_t unregister_instance_w_timestamp (const Foo &instance_data, const DDS_InstanceHandle_t &handle, const DDS_Time_t &source_timestamp)=0
 Performs the same function as FooDataWriter::unregister_instance except that it also provides the value for the source_timestamp. More...
 
virtual DDS_ReturnCode_t unregister_instance_w_params (const Foo &instance_data, DDS_WriteParams_t &params)=0
 Performs the same function as FooDataWriter::unregister_instance and FooDataWriter::unregister_instance_w_timestamp except that it also provides the values contained in params. More...
 
virtual DDS_ReturnCode_t write (const Foo &instance_data, const DDS_InstanceHandle_t &handle)=0
 Modifies the value of a data instance. More...
 
virtual DDS_ReturnCode_t write_w_timestamp (const Foo &instance_data, const DDS_InstanceHandle_t &handle, const DDS_Time_t &source_timestamp)=0
 Performs the same function as FooDataWriter::write except that it also provides the value for the source_timestamp. More...
 
virtual DDS_ReturnCode_t write_w_params (const Foo &instance_data, DDS_WriteParams_t &params)=0
 Performs the same function as FooDataWriter::write and FooDataWriter::write_w_timestamp except that it also provides the values contained in params. More...
 
virtual DDS_ReturnCode_t dispose (const Foo &instance_data, const DDS_InstanceHandle_t &instance_handle)=0
 Requests the middleware to delete the instance. More...
 
virtual DDS_ReturnCode_t dispose_w_timestamp (const Foo &instance_data, const DDS_InstanceHandle_t &instance_handle, const DDS_Time_t &source_timestamp)=0
 Performs the same functions as dispose except that the application provides the value for the source_timestamp that is made available to DDSDataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. More...
 
virtual DDS_ReturnCode_t dispose_w_params (const Foo &instance_data, DDS_WriteParams_t &params)=0
 Performs the same function as FooDataWriter::dispose and FooDataWriter::dispose_w_timestamp except that it also provides the values contained in params. More...
 
virtual DDS_ReturnCode_t get_key_value (Foo &key_holder, const DDS_InstanceHandle_t &handle)=0
 Retrieve the instance key that corresponds to an instance handle. More...
 
virtual DDS_InstanceHandle_t lookup_instance (const Foo &key_holder)=0
 Retrieve the instance handle that corresponds to an instance key_holder. More...
 
virtual void * create_data (const DDS_TypeAllocationParams_t &alloc_params=DDS_TYPE_ALLOCATION_PARAMS_DEFAULT)
 Creates a data sample and initializes it. More...
 
virtual DDS_Boolean delete_data (void *sample, const DDS_TypeDeallocationParams_t &dealloc_params=DDS_TYPE_DEALLOCATION_PARAMS_DEFAULT)
 Destroys a user data type instance. More...
 
virtual DDS_ReturnCode_t get_loan (TData *&sample)
 Gets a sample managed by the DataWriter. More...
 
virtual DDS_ReturnCode_t discard_loan (TData &sample)
 Returns a loaned sample back to the DataWriter. More...
 
- Public Member Functions inherited from DDSDataWriter
virtual DDS_ReturnCode_t get_liveliness_lost_status (DDS_LivelinessLostStatus &status)
 Accesses the DDS_LIVELINESS_LOST_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_offered_deadline_missed_status (DDS_OfferedDeadlineMissedStatus &status)
 Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_offered_incompatible_qos_status (DDS_OfferedIncompatibleQosStatus &status)
 Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_publication_matched_status (DDS_PublicationMatchedStatus &status)
 Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_reliable_writer_cache_changed_status (DDS_ReliableWriterCacheChangedStatus &status)
 <<extension>> Get the reliable cache status for this writer. More...
 
virtual DDS_ReturnCode_t get_reliable_reader_activity_changed_status (DDS_ReliableReaderActivityChangedStatus &status)
 <<extension>> Get the reliable reader activity changed status for this writer. More...
 
virtual DDS_ReturnCode_t get_datawriter_cache_status (DDS_DataWriterCacheStatus &status)
 <<extension>> Get the datawriter cache status for this writer. More...
 
virtual DDS_ReturnCode_t get_datawriter_protocol_status (DDS_DataWriterProtocolStatus &status)
 <<extension>> Get the datawriter protocol status for this writer. More...
 
virtual DDS_ReturnCode_t get_matched_subscription_datawriter_protocol_status (DDS_DataWriterProtocolStatus &status, const DDS_InstanceHandle_t &subscription_handle)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. More...
 
virtual DDS_ReturnCode_t is_matched_subscription_active (DDS_Boolean &is_active, const DDS_InstanceHandle_t &subscription_handle)
 Check if a subscription currently matched with a DataWriter is active. More...
 
virtual DDS_ReturnCode_t get_service_request_accepted_status (DDS_ServiceRequestAcceptedStatus &status)
 Accesses the DDS_SERVICE_REQUEST_ACCEPTED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_matched_subscription_datawriter_protocol_status_by_locator (DDS_DataWriterProtocolStatus &status, const DDS_Locator_t &locator)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator. More...
 
virtual DDS_ReturnCode_t assert_liveliness ()
 This operation manually asserts the liveliness of this DDSDataWriter. More...
 
virtual DDS_ReturnCode_t get_matched_subscription_locators (DDS_LocatorSeq &locators)
 <<extension>> Retrieve the list of locators for subscriptions currently "associated" with this DDSDataWriter. More...
 
virtual DDS_ReturnCode_t get_matched_subscriptions (DDS_InstanceHandleSeq &subscription_handles)
 Retrieve the list of subscriptions currently "associated" with this DDSDataWriter. More...
 
virtual DDS_ReturnCode_t get_matched_subscription_data (DDS_SubscriptionBuiltinTopicData &subscription_data, const DDS_InstanceHandle_t &subscription_handle)
 This operation retrieves the information on a subscription that is currently "associated" with the DDSDataWriter. More...
 
virtual DDS_ReturnCode_t get_matched_subscription_participant_data (DDS_ParticipantBuiltinTopicData &participant_data, const DDS_InstanceHandle_t &subscription_handle)
 This operation retrieves the information on the discovered DDSDomainParticipant associated with the subscription that is currently matching with the DDSDataWriter. More...
 
virtual DDSTopicget_topic ()
 This operation returns the DDSTopic associated with the DDSDataWriter. More...
 
virtual DDSPublisherget_publisher ()
 This operation returns the DDSPublisher to which the DDSDataWriter belongs. More...
 
virtual DDS_ReturnCode_t wait_for_acknowledgments (const DDS_Duration_t &max_wait)
 Blocks the calling thread until all data written by reliable DDSDataWriter entity is acknowledged, or until timeout expires. More...
 
virtual DDS_ReturnCode_t is_sample_app_acknowledged (DDS_Boolean &is_app_ack, const struct DDS_SampleIdentity_t &identity)
 This method can be used to see if a sample has been application acknowledged. More...
 
virtual DDS_ReturnCode_t wait_for_asynchronous_publishing (const DDS_Duration_t &max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete. More...
 
virtual DDS_ReturnCode_t set_qos (const DDS_DataWriterQos &qos)
 Sets the writer QoS. More...
 
virtual DDS_ReturnCode_t set_property (const char *property_name, const char *value, bool propagate)
 Set the value for a property that applies to a DataWriter. More...
 
virtual DDS_ReturnCode_t set_qos_with_profile (const char *library_name, const char *profile_name)
 <<extension>> Change the QoS of this writer using the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t get_qos (DDS_DataWriterQos &qos)
 Gets the writer QoS. More...
 
virtual DDS_ReturnCode_t set_listener (DDSDataWriterListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)
 Sets the writer listener. More...
 
virtual DDSDataWriterListenerget_listener ()
 Get the writer listener. More...
 
virtual DDS_ReturnCode_t flush ()
 <<extension>> Flushes the batch in progress in the context of the calling thread. More...
 
virtual DDS_ReturnCode_t take_discovery_snapshot ()
 Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...
 
virtual DDS_ReturnCode_t take_discovery_snapshot (const char *file_name)
 Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...
 
virtual DDS_ReturnCode_t enable ()
 Enables the DDSEntity. More...
 
virtual DDSStatusConditionget_statuscondition ()
 Allows access to the DDSStatusCondition associated with the DDSEntity. More...
 
virtual DDS_StatusMask get_status_changes ()
 Retrieves the list of communication statuses in the DDSEntity that are triggered. More...
 
virtual DDS_InstanceHandle_t get_instance_handle ()
 Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...
 
virtual DDS_ReturnCode_t enable ()=0
 Enables the DDSEntity. More...
 
virtual DDSStatusConditionget_statuscondition ()=0
 Allows access to the DDSStatusCondition associated with the DDSEntity. More...
 
virtual DDS_StatusMask get_status_changes ()=0
 Retrieves the list of communication statuses in the DDSEntity that are triggered. More...
 
virtual DDS_InstanceHandle_t get_instance_handle ()=0
 Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...
 

Static Public Member Functions

static FooDataWriternarrow (DDSDataWriter *writer)
 Narrow the given DDSDataWriter pointer to a FooDataWriter pointer. More...
 

Detailed Description

<<interface>> <<generic>> User data type specific data writer.

Defines the user data type specific writer interface generated for each application class.

The concrete user data type writer automatically generated by the implementation is an incarnation of this class.

See also
DDSDataWriter
Foo
FooDataReader
the Code Generator User's Manual

Member Function Documentation

◆ narrow()

static FooDataWriter * FooDataWriter::narrow ( DDSDataWriter writer)
static

Narrow the given DDSDataWriter pointer to a FooDataWriter pointer.

Check if the given writer is of type FooDataWriter.

Parameters
writer<<in>> Base-class DDSDataWriter to be converted to the auto-generated class FooDataWriter that extends DDSDataWriter.
Returns
FooDataWriter if writer is of type Foo. Return NULL otherwise.

◆ register_instance()

virtual DDS_InstanceHandle_t FooDataWriter::register_instance ( const Foo instance_data)
pure virtual

Informs RTI Connext 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 DDS_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 RTI Connext 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 DDS_HANDLE_NIL as the DDS_InstanceHandle_t parameter to the write or dispose operation and RTI Connext will auto-register the instance.

For best performance, the operation should be invoked prior to calling any operation that modifies the instance, such as FooDataWriter::write, FooDataWriter::write_w_timestamp, FooDataWriter::dispose and FooDataWriter::dispose_w_timestamp and the handle used in conjunction with the data for those calls.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is used.

This operation may fail and return DDS_HANDLE_NIL if DDS_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 DDSDataWriter has been enabled. Otherwise, DDS_HANDLE_NIL will be returned.

Parameters
instance_data<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function.
Returns
For keyed data type, a handle that can be used in the calls that take a DDS_InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS_HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always returns DDS_HANDLE_NIL.
See also
FooDataWriter::unregister_instance, FooDataWriter::get_key_value, Relationship between registration, liveliness and ownership

◆ register_instance_w_timestamp()

virtual DDS_InstanceHandle_t FooDataWriter::register_instance_w_timestamp ( const Foo instance_data,
const DDS_Time_t source_timestamp 
)
pure virtual

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 DDS_ResourceLimitsQosPolicy::max_instances limit has been exceeded.

This operation can only be called after DDSDataWriter has been enabled. Otherwise, DDS_HANDLE_NIL will be returned.

Parameters
instance_data<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function.
source_timestamp<<in>> The 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.
Returns
For keyed data type, return a handle that can be used in the calls that take a DDS_InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS_HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return DDS_HANDLE_NIL.
See also
FooDataWriter::unregister_instance, FooDataWriter::get_key_value

◆ register_instance_w_params()

virtual DDS_InstanceHandle_t FooDataWriter::register_instance_w_params ( const Foo instance_data,
DDS_WriteParams_t params 
)
pure virtual

Performs the same function as FooDataWriter::register_instance and FooDataWriter::register_instance_w_timestamp except that it also provides the values contained in params.

See also
FooDataWriter::write_w_params

◆ unregister_instance()

virtual DDS_ReturnCode_t FooDataWriter::unregister_instance ( const Foo instance_data,
const DDS_InstanceHandle_t handle 
)
pure virtual

Reverses the action of FooDataWriter::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 FooDataWriter::register_instance. Otherwise, this operation may fail with DDS_RETCODE_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, RTI Connext will automatically supply the value of the source_timestamp that is used.

This operation informs RTI Connext that the DDSDataWriter is no longer going to provide any information about the instance. This operation also indicates that RTI Connext can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling this function.

The special value DDS_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 DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the handle is any value other than DDS_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). RTI Connext will treat as if the unregister_instance() operation is for the instance as indicated by the handle.

If, after a FooDataWriter::unregister_instance, the application wants to modify (FooDataWriter::write or FooDataWriter::dispose) an instance, it has to register it again, or else use the special handle value DDS_HANDLE_NIL.

This operation does not indicate that the instance is deleted (that is the purpose of FooDataWriter::dispose). The operation FooDataWriter::unregister_instance just indicates that the DDSDataWriter no longer has anything to say about the instance. DDSDataReader entities that are reading the instance may receive a sample with DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other DDSDataWriter objects writing that same instance.

DDS_WriterDataLifecycleQosPolicy::autodispose_unregistered_instances controls whether instances are automatically disposed when they are unregistered.

This operation can affect the ownership of the data instance (see OWNERSHIP). If the DDSDataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.

If DDS_ReliabilityQosPolicy::kind is set to DDS_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 DDS_ReliabilityQosPolicy::max_blocking_time; if this writer is still unable to unregister after that period, this method will fail with DDS_RETCODE_TIMEOUT.

Parameters
instance_data<<in>> The instance that should be unregistered. If Foo has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER .
handle<<in>> represents the instance to be unregistered. If Foo has a key and handle is DDS_HANDLE_NIL, handle is not used and instance is deduced from instance_data. If Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT or DDS_RETCODE_NOT_ENABLED
See also
FooDataWriter::register_instance
FooDataWriter::unregister_instance_w_timestamp
FooDataWriter::get_key_value
Relationship between registration, liveliness and ownership

◆ unregister_instance_w_timestamp()

virtual DDS_ReturnCode_t FooDataWriter::unregister_instance_w_timestamp ( const Foo instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t source_timestamp 
)
pure virtual

Performs the same function as FooDataWriter::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 FooDataWriter::unregister_instance operation.

This operation may block and may time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for the unregister_instance operation.

Parameters
instance_data<<in>> The instance that should be unregistered. If Foo has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER.
handle<<in>> represents the instance to be unregistered. If Foo has a key and handle is DDS_HANDLE_NIL, handle is not used and instance is deduced from instance_data. If Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER.
source_timestamp<<in>> The 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.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter::register_instance
FooDataWriter::unregister_instance
FooDataWriter::get_key_value

◆ unregister_instance_w_params()

virtual DDS_ReturnCode_t FooDataWriter::unregister_instance_w_params ( const Foo instance_data,
DDS_WriteParams_t params 
)
pure virtual

Performs the same function as FooDataWriter::unregister_instance and FooDataWriter::unregister_instance_w_timestamp except that it also provides the values contained in params.

See also
FooDataWriter::write_w_params
FooDataWriter::dispose_w_params

◆ write()

virtual DDS_ReturnCode_t FooDataWriter::write ( const Foo instance_data,
const DDS_InstanceHandle_t handle 
)
pure virtual

Modifies the value of a data instance.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is made available to DDSDataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo and DESTINATION_ORDER QoS policy for details).

As a side effect, this operation asserts liveliness on the DDSDataWriter itself, the DDSPublisher and the DDSDomainParticipant.

Note that the special value DDS_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 DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the handle is any value other than DDS_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). RTI Connext 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 DDS_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.

This operation may also block when using DDS_BEST_EFFORT_RELIABILITY_QOS and DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS. In this case, the DDSDataWriter will queue DDS samples until they are sent by the asynchronous publishing thread. The number of DDS samples that can be stored is determined by the DDS_HistoryQosPolicy. If the asynchronous thread does not send DDS samples fast enough (such as when using a slow DDSFlowController, the queue may fill up. In that case, subsequent write calls will block.

If DDS_ReliabilityQosPolicy::max_blocking_time elapses before the DDSDataWriter can store the modification without exceeding the limits, the operation will fail and return DDS_RETCODE_TIMEOUT for KEEP_ALL configurations.

Here is how the write operation behaves when DDS_KEEP_LAST_HISTORY_QOS and DDS_RELIABLE_RELIABILITY_QOS are used:

Here is how the write operation behaves when DDS_KEEP_ALL_HISTORY_QOS and DDS_RELIABLE_RELIABILITY_QOS are used:

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter::unregister_instance may help freeing up some resources.

This operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if the timestamp is less than the timestamp used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp).

If an instance obtained from FooDataWriter::get_loan is modified with this operation, then all instances modified thereafter should be from FooDataWriter::get_loan.

See DDS_ReliabilityQosPolicyAcknowledgmentModeKind for more information on the following notes:

(1) A sample in the writer history is considered "protocol ACKed" when the sample has been individually ACKed at the RTPS protocol level by each one of the DataReaders that matched the DataWriter at the moment the sample was added to the writer queue.

  • Late joiners do not change the protocol ACK state of a sample. If a sample is marked as protocol ACKed because it has been acknowledged by all the matching DataReaders and a DataReader joins later on, the historical sample is still considered protocol ACKed even if it has not been received by the late joiner.
  • If a sample 'S1' is protocol ACKed and a TopicQuery is received, triggering the publication of 'S1', the sample is still considered protocol ACKed. If a sample 'S1' is not ACKed and a TopicQuery is received triggering the publication of 'S1', the DataWriter will require that both the matching DataReaders on the live RTPS channel and the DataReader on the TopicQuery channel individually protocol ACK the sample in order to consider the sample protocol ACKed.

(2) A sample in the writer history is considered "fully ACKed" when all of the following conditions are met:

(3) It is possible within a single call to the write operation for a DataWriter to block both when the send window is full and then again when DDS_ResourceLimitsQosPolicy::max_samples or DDS_ResourceLimitsQosPolicy::max_samples_per_instance is exceeded. This can happen because blocking on the send window only considers protocol-ACKed samples, while blocking based on resource limits considers fully-ACKed samples. In any case, the total max blocking time of a single call to the write operation will not exceed DDS_ReliabilityQosPolicy::max_blocking_time.

Parameters
instance_data<<in>> The data to write.
Parameters
handle<<in>> Either the handle returned by a previous call to FooDataWriter::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 method may fail with DDS_RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_OUT_OF_RESOURCES, or DDS_RETCODE_NOT_ENABLED.
MT Safety:
It is UNSAFE to modify instance_data before the operation has finished. The operation is otherwise SAFE.
See also
DDSDataReader
FooDataWriter::write_w_timestamp
DESTINATION_ORDER

◆ write_w_timestamp()

virtual DDS_ReturnCode_t FooDataWriter::write_w_timestamp ( const Foo instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t source_timestamp 
)
pure virtual

Performs the same function as FooDataWriter::write except that it also provides the value for the source_timestamp.

Explicitly provides the timestamp that will be available to the DDSDataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_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 FooDataWriter::write operation.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for FooDataWriter::write.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter::unregister_instance may help free up some resources.

This operation may fail with DDS_RETCODE_BAD_PARAMETER under the same circumstances described for the write operation.

Parameters
instance_data<<in>> The data to write.
handle<<in>> Either the handle returned by a previous call to FooDataWriter::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 method may fail with DDS_RETCODE_BAD_PARAMETER.
source_timestamp<<in>> When using DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS the timestamp value must be greater than or equal to the timestamp value used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp) However, if it is less than the timestamp of the previous operation but the difference is less than the DDS_DestinationOrderQosPolicy::source_timestamp_tolerance, the timestamp of the previous operation will be used as the source timestamp of this sample. Otherwise, if the difference is greater than DDS_DestinationOrderQosPolicy::source_timestamp_tolerance, the function will return DDS_RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_OUT_OF_RESOURCES, or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter::write
DDSDataReader
DESTINATION_ORDER

◆ write_w_params()

virtual DDS_ReturnCode_t FooDataWriter::write_w_params ( const Foo instance_data,
DDS_WriteParams_t params 
)
pure virtual

Performs the same function as FooDataWriter::write and FooDataWriter::write_w_timestamp except that it also provides the values contained in params.

Allows provision of the sample identity, related sample identity, source timestamp, instance handle, and publication priority contained in params.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumstances described for FooDataWriter::write.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter::unregister_instance_w_params may help free up some resources.

This operation may fail with DDS_RETCODE_BAD_PARAMETER under the same circumstances described for the FooDataWriter::write.

Parameters
instance_data<<in>> The data to write.
params<<inout>> The write parameters. Note that this is an inout parameter if you activate DDS_WriteParams_t::replace_auto; otherwise it won't be modified.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter::write
DDSDataReader

◆ dispose()

virtual DDS_ReturnCode_t FooDataWriter::dispose ( const Foo instance_data,
const DDS_InstanceHandle_t instance_handle 
)
pure virtual

Requests the middleware to delete the instance.

This operation is useful only for keyed data types. Using it for non-keyed types has no effect and reports no error.

When an instance is disposed, the DDSDataWriter communicates this state change to DDSDataReader objects by propagating a dispose sample. When the instance changes to a disposed state, you can see the state change on the DataReader by looking at DDS_SampleInfo::instance_state. Disposed instances have the value DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE.

The resources allocated to dispose instances on the DataWriter are not removed by default. The removal of the resources allocated to a dispose instance on the DataWriter queue can be controlled by using the QoS DDS_WriterDataLifecycleQosPolicy::autopurge_disposed_instances_delay.

Likewise, on the DataReader, the removal of the resources associated with an instance in the dispose state can be controlled by using the QoS DDS_ReaderDataLifecycleQosPolicy::autopurge_disposed_instances_delay.

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, RTI Connext will automatically supply the value of the source_timestamp that is made available to DDSDataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the FooDataWriter::unregister_instance operation.

The special value DDS_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 instance_handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the instance_handle is any value other than DDS_HANDLE_NIL, and the instance_handle 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). In this case, the instance that will be disposed is the instance corresponding to the instance_handle, not to the instance_data.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumstances described for FooDataWriter::write.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter::unregister_instance may help free up some resources.

Parameters
instance_data<<in>> The data to dispose. If Foo has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used.
instance_handle<<in>> Either the handle returned by a previous call to FooDataWriter::register_instance, or else the special value DDS_HANDLE_NIL. If Foo has a key and instance_handle is DDS_HANDLE_NIL, instance_handle is not used and it is deduced from instance_data. If Foo has no key, instance_handle is not used. If instance_handle is used, it must represent an instance of type Foo that has been written or registered with this writer. Otherwise, this method fail with DDS_RETCODE_BAD_PARAMETER. If Foo has a key, instance_handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter::dispose_w_timestamp
Relationship between registration, liveliness and ownership

◆ dispose_w_timestamp()

virtual DDS_ReturnCode_t FooDataWriter::dispose_w_timestamp ( const Foo instance_data,
const DDS_InstanceHandle_t instance_handle,
const DDS_Time_t source_timestamp 
)
pure virtual

Performs the same functions as dispose except that the application provides the value for the source_timestamp that is made available to DDSDataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the FooDataWriter::dispose operation.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for FooDataWriter::write.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter::unregister_instance may help freeing up some resources.

Parameters
instance_data<<in>> The data to dispose. If Foo has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used.
instance_handle<<in>> Either the handle returned by a previous call to FooDataWriter::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 method may fail with DDS_RETCODE_BAD_PARAMETER.
source_timestamp<<in>> The 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 DDSDataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter::dispose

◆ dispose_w_params()

virtual DDS_ReturnCode_t FooDataWriter::dispose_w_params ( const Foo instance_data,
DDS_WriteParams_t params 
)
pure virtual

Performs the same function as FooDataWriter::dispose and FooDataWriter::dispose_w_timestamp except that it also provides the values contained in params.

See also
FooDataWriter::write_w_params

◆ get_key_value()

virtual DDS_ReturnCode_t FooDataWriter::get_key_value ( Foo key_holder,
const DDS_InstanceHandle_t handle 
)
pure virtual

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 type has no keys, this method has no effect and exits with no error.

For keyed data types, this operation may fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDSDataWriter.

Parameters
key_holder<<inout>> a user data type specific key holder, whose key fields are filled by this operation. If Foo has no key, this method has no effect.
Parameters
handle<<in>> the instance whose key is to be retrieved. If Foo has a key, handle must represent a registered instance of type Foo. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER. If Foo has a key and handle is DDS_HANDLE_NIL, this method will fail with DDS_RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See also
FooDataReader::get_key_value

◆ lookup_instance()

virtual DDS_InstanceHandle_t FooDataWriter::lookup_instance ( const Foo key_holder)
pure virtual

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 RTI Connext is unable to provide an instance handle, RTI Connext will return the special value HANDLE_NIL.

Parameters
key_holder<<in>> a user data type specific key holder.
Returns
the instance handle associated with this instance. If Foo has no key, this method has no effect and returns DDS_HANDLE_NIL

◆ create_data()

virtual void * FooDataWriter::create_data ( const DDS_TypeAllocationParams_t alloc_params = DDS_TYPE_ALLOCATION_PARAMS_DEFAULT)
inlinevirtual

Creates a data sample and initializes it.

The behavior of this API is identical to FooTypeSupport::create_data.

Parameters
alloc_params<<in>> Whether or not to recursively allocate pointers and/or optional members
Returns
Newly created data type, or NULL on failure.
See also
FooDataWriter::delete_data

◆ delete_data()

virtual DDS_Boolean FooDataWriter::delete_data ( void *  sample,
const DDS_TypeDeallocationParams_t dealloc_params = DDS_TYPE_DEALLOCATION_PARAMS_DEFAULT 
)
inlinevirtual

Destroys a user data type instance.

The behavior of this API is identical to FooTypeSupport::delete_data.

Parameters
sample<<in>> Cannot be NULL.
dealloc_params<<in>> Whether or not to destroy pointers and/or optional members. By default they are destroyed (deleted).
Returns
DDS_BOOLEAN_TRUE on success.
See also
FooDataWriter::create_data

◆ get_loan()

virtual DDS_ReturnCode_t FooDataWriter::get_loan ( TData *&  sample)
inlinevirtual

Gets a sample managed by the DataWriter.

This operation is supported while using Zero Copy transfer over shared memory" or \ref RTIFlatDataModule "FlatData language binding". For FlatData types, this function should be used directly if the type is final; if the type is mutable, rti::flat::build_data() should be used to obtain a sample builder to work with the loaned sample.

The loaned sample is obtained from a DataWriter-managed sample pool and is uninitialized by default. An initialized sample can be obtained by setting DDS_DataWriterResourceLimitsQosPolicy::initialize_writer_loaned_sample to DDS_BOOLEAN_TRUE. The DDS_DataWriterResourceLimitsQosPolicy::writer_loaned_sample_allocation settings can be used to configure the DataWriter-managed sample pool.

FooDataWriter::get_loan fails with DDS_RETCODE_OUT_OF_RESOURCES if DDS_AllocationSettings_t::max_count samples have been loaned, and none of those samples has been written with FooDataWriter::write or discarded via FooDataWriter::discard_loan.

Samples returned from FooDataWriter::get_loan have an associated state. Due to the optimized nature of the write operation while using Zero Copy transfer over shared memory or FlatData language binding, this sample state is used to control when a sample is available for reuse after the write operation. The possible sample states are free, allocated, removed or serialized. A sample that has never been allocated is "free". FooDataWriter::get_loan takes a "free" or "removed" sample and makes it "allocated". When a sample is written, its state transitions from "allocated" to "serialized", and the DataWriter takes responsibility for returning the sample back to its sample pool. The sample remains in the "serialized" state until it is removed from the DataWriter queue. For a reliable DataWriter, the sample is removed from the DataWriter's queue when the sample is acknowledged by all DataReaders. For a best-effort DataWriter, the sample is removed from the queue immediately after the write operation. After the sample is removed from the DataWriter queue, the sample is put back into the sample pool, and its state transitions from "serialized" to "removed". At this time, a new call to FooDataWriter::get_loan may return the same sample.

A loaned sample should not be reused to write a new value after the first write operation. Instead, a new sample from FooDataWriter::get_loan should be used to write the new value. A loaned sample that has not been written can be returned to the DataWriter's sample pool by using FooDataWriter::discard_loan. If the write operation fails, then the sample can be used again with a write or discard_loan operation. Disposing or unregistering an instance with loaned samples follows the same pattern. A loaned sample used successfully with a dispose or unregister operation cannot be used again. But if the dispose or unregister operation fails, the sample is available for reuse.

A DataWriter cannot write managed samples (created with get_loan) and unmanaged samples (created in any other way) at the same time. The first call to get_loan automatically prepares this DataWriter to work with managed samples. Calls to get_loan will fail with DDS_RETCODE_PRECONDITION_NOT_MET if an unmanaged sample was written with this DataWriter earlier. Similarly, FooDataWriter::write will fail to write an unmanaged sample if get_loan was called.

Parameters
sample<<inout>> reference to a user data type pointer. The loaned sample is returned via this sample.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.
See also
FooDataWriter::discard_loan

◆ discard_loan()

virtual DDS_ReturnCode_t FooDataWriter::discard_loan ( TData &  sample)
inlinevirtual

Returns a loaned sample back to the DataWriter.

This operation is supported while using Zero Copy transfer over shared memory" or the FlatData language binding.

A loaned sample that hasn't been written can be returned to the DataWriter with this operation.

Parameters
sample<<in>> loaned sample to be discarded.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter::get_loan