Home

User`s Manual - Community RTI Connext Users

1. Configures whether or not the service state must be per sisted on disk In addition when the state is persisted you can select whether or not to restore it when the service is restarted Example lt persistence gt lt kind gt PERSISTENT lt kind gt lt restore gt true lt restore gt lt persistence gt There are two values for the kind lt persistence gt VOLATILE Do not persist service state 0or1 e PERSISTENT Persist service state Note If this policy s kind is configured as VOLATILE and there are changes to the configuration as a result of running remote administration commands when the service is restarted these changes will be lost See Queuing Service Persistency Section 2 14 Defaults kind VOLATILE restore true lt shared_reader_queue_replication gt Enables SharedReaderQueue replication See Chapter 7 High Availability vord 3 3 3 1 When remote administration is enabled Queuing Service will create a DomainParticipant Pub lisher Subscriber DataWriter and DataReader These entities are used to receive commands and send responses You can configure these entities with QoS tags within the lt administration gt tag Table 3 4 Remote Administration Tags lists the tags allowed within lt administration gt tag Notice that the lt domain_id gt tag is required For more details please see Chapter 5 Administering Queuing Service from a Remote Location Note The
2. The following command is used to delete a SharedSubscriber DELETE lt target gueuing service gt lt shared subscriber resource identifier gt Return Value Upon success this command returns RTI SERVICE COMMAND REPLY OK in the retcode field of the reply Otherwise this command returns RTI SERVICE COMMAND REPLY ERROR and the field string body contains a human read able string describing the error Accessing Queuing Service from a Connext DDS application You can create a DataWriter for the command topic to write Oueuing Service administration com mands and create a DataReader for the response topic to receive responses A more powerful and easier way is to use the Reguest Reply API only available with Connext DDS Professional You can create a Reguester for these topics that will write command reguests and wait for replies The QoS configurations of your DataWriter and DataReader or your Requester if you are using the Request Reply API must be compatible with the one used by Oueuing Service see how this is configured in Configuring Administration Section 3 3 3 5 9 Accessing Oueuing Service from a Connext DDS application The following C example uses the Connext DDS Professional Reguest Reply API to send com mands and receive replies This example shows a C application that creates a Requester that can communicate with the Oueuing Service remote administration server It sends a reguest a Oueu ing Service
3. lt mask gt MASK DEFAULT lt mask gt lt priority gt THREAD PRIORITY DEFAULT lt priority gt lt stack size gt THREAD STACK SIZE DEFAULT lt stack size gt lt thread gt lt session gt Defaults e mask MASK DEFAULT e priority THREAD PRIORITY DEFAULT e Stack size THREAD STACK SIZE DEFAULT 0or1 3 20 XML Tags for Configuring Queuing Service 3 3 10 Configuring SharedReaderQueues A SharedReaderQueue is a logical DataReader queue hosted inside a SharedSubscriber that pro vides exactly once or at most once access to the Consumers attached to the SharedReader Queue It is associated with a Topic and the name of the SharedReaderQueue is derived from the name of the Topic and the SharedSubscriber that hosts it Implementation wise a SharedReader Queue is composed of an input DDS DataReader and output DDS DataWriter pair that together with a queue storage implement the queuing behavior for a Topic The input DataReader is matched to the DataWriters associated with the QueueProducers and the output DataWriter is matched to the DataReaders associated with the QueueConsumers The pro cessing logic ensures that each sample in the SharedReaderQueue is delivered to only one of the QueueConsumers LJ Table 3 14 SharedReaderQueue Tags and Table 3 15 Queue QoS Tags describe the tags allowed within lt shared_reader_queue gt I Table 3 16 lt shared_reader_queue gt Attributes describes the
4. lt distribution gt Round Robin Dispatch Policy with Explicit AueueConsumer Availability Feedback This dispatch mode uses a QueueConsumer Availability Topic which is published by the QueueConsumers and provides information about the capability of the QueueConsumer to pro cess messages from Queuing Service The round robin will be done among the QueueConsumers that are available The ConsumerAvailability topic name is as follows ConsumerAvailability lt SharedReader QueueName gt where lt SharedReaderQueueName gt is lt SharedReaderQueueTopicName gt lt Shared SubscriberName gt The topic type is the following and can be found in lt NDDSHOME gt resource idl QueuingSer viceTypes idl struct ConsumerAvailability t GUID_t consumer_guid key boolean reception enabled long unacked threshold Extensibility EXTENSIBLE EXTENSIBILITY The type is registered with the following name RTI QueuingService ConsumerAvailability_t A QueueConsumer can report its availability by updating the unacked_threshold and reception_enabled fields The unacked_threshold field is equivalent to the threshold parameter described in Round Robin Dispatch Policy without Explicit QueueConsumer Availability Feed back Section 2 10 1 but it can be set per QueueConsumer In addition a QueueConsumer can indicate that it does not want to receive any samples from Queuing Service by setting the field reception_enabled to DDS_BOOLEAN_FALSE The
5. L QueuingServiceName A string label that uniquely identifies a QueuingService instance running within a DDS domain LJ SharedSubscriber A container that hosts SharedReaderQueues allowing remote QueueConsumers to attach to the shared queues and providing exactly once or at most once access to the samples in the shared queues With these access modes when one QueueConsumer gets a message the other QueueConsumers attached to the same SharedReaderQueue do not get that message A SharedSubscriber can host one or more SharedReaderQueues each one associated with a different DDS Topic name LJ SharedSubscriberName A string label that uniquely identifies a SharedSubscriber within a DDS domain L SharedReaderQueue A logical DataReader queue hosted inside a SharedSubscriber that provides exactly once or at most once access to the Consumers attached to the Share dReaderQueue It is associated with a Topic and the name of the SharedReaderQueue is derived from the name of the Topic and the SharedSubscriber that hosts it Implementa tion wise a SharedReaderQueue is composed of an input DDS DataReader and output DDS DataWriter pair that together with a queue storage implement the queuing behavior for a Topic The input DataReader is matched to the DataWriters associated with the Queue Producers and the output DataWriter is matched to the DataReaders associated with the Queue Consumers The processing logic ensures that each sample in the
6. Note This tag only applies to PERSISTENT SharedReaderQueues cre ated with lt in_memory_state gt set to true see Configuring Share dReaderQueues Section 3 3 10 0or1 lt file_prefix gt Specifies a name prefix associated with all the files created by Queuing Service This prefix can also be provided by and is overridden by the persis tentFilePrefix command line option Default Value provided with persistentFilePrefix or QS if the com mand line option is not provided Oorl lt journal_mode gt Sets the journal mode of the persistent storage This tag can take these values DELETE Deletes the rollback journal at the conclusion of each transaction e MEMORY Stores the rollback journal in volatile RAM This saves disk I O e OFF Completely disables the rollback journal If the application crashes in the middle of a transaction when the journal mode is set to OFF the files containing the samples will very likely be cor rupted e PERSIST Prevents the rollback journal from being deleted at the end of each transaction Instead the header of the journal is over ridden with zeros e TRUNCATE Commits transactions by truncating the rollback journal to zero length instead of deleting it e WAL Uses a write ahead log instead of a rollback journal to implement transactions Default DELETE Note This does not apply to PERSISTENT SharedReaderQueues cre ated with lt in_memory_state gt set to
7. The Connext DDS API Reference HTML documentation contains the full API documentation for the QueueProducer Under the Modules tab navigate to RTI Connext DDS API Reference RTI Connext Messaging API Reference Queuing Pattern QueueProducer QueueConsumer Wrapper To simplify the use and configuration of a DataReader to receive samples from a SharedReader Queue Connext provides an abstraction QueueConsumer lt MessageType gt which wraps the DataReader and provide additional services such as an operation to detect if there is a matching SharedReaderQueue or a blocking operation to receive samples The Connext API Reference HTML documentation contains the full API documentation for the QueueProducer Under the Modules tab navigate to RTI Connext DDS API Reference RTI Connext Messaging API Reference Queuing Pattern QueueConsumer QueueRequester Wrapper To simplify the use and configuration of the DataReader and DataWriter in the requester applica tion Connext provides an abstraction QueueRequester lt MessageRequestType MessageRep 8 1 QueueReplier Wrapper 8 4 lyType gt which wraps the DataReader and DataWriter usage and provide additional services such as an operation to wait for the response for a given reguest The Connext API Reference HTML documentation contains the full API documentation for the OueueProducer Under the Modules tab navigate to RTI Connext DDS API Reference RTI Connext Messaging API Referenc
8. lt element gt lt value gt lt property gt lt participant_qos gt 9 3 Asymmetric TCP Communication with Oueuing Service And Replication 9 2 Figure 9 2 Asymmetric TCP Communication with Queuing Service And Replication In this scenario one of more instances of Queuing Service are behind a NAT Firewall and the OueueProducers QueueConsumers and Remote Administration applications run outside the NAT The Queuing Service instances are configured to replicate SharedReaderOueues and config uration Figure 9 2 shows how to configure the system to communicate using the TCP transport This includes communication with the applications running outside the NAT and communication between the Oueuing Service instances Asymmetric TCP Configuration With Replication QS Instance 1 QS Instance 2 Private IP address 192 168 5 12 Private IP address 192 168 5 11 Producer Consumer port 16000 QS replication sync port 16001 Producer Consumer port 15000 QS replication sync port 15001 WANIP address 18 181 0 32 WANIP address 18 181 0 32 Remote admin port 15002 Remote admin AS sync port 15003 Remote admin port 16002 Port forward settings Remote admin AS sync port 16003 Port forward settings WAN port 15000 to 192 168 5 11 15000 WAN port 15001 to 192 168 5 11 15001 Configuration replication port 15004 Configuration replication AS sync port Configuration replication port 16
9. lt statistics sampling period If the tag is not defined the period is 1 second The statistic sampling period defined in lt gueuing service gt is inherited by all the entities inside lt gueuing service gt An entity can override the period 0or1 Table 3 8 Persistence Setting Tags Tags within lt persistence_settings gt Description Number of Tags Allowed lt filesystem gt the Configures the file system settings used to persist the service state and SharedReaderOueues states See Table 3 9 Filesystem Tags 0or1 3 15 XML Tags for Configuring Queuing Service Table 3 9 Filesystem Tags Tags within lt filesystem gt Description Number of Tags Allowed lt directory gt Specifies the directory of the files in which the service state and the SharedReaderQueues states will be persisted This directory can also be provided by and is overridden by the persistentStoragePath command line option The directory must exist otherwise the service will report an error upon start up Default Value provided with persistentStoragePath or the current working directory if the command line option is not provided Oorl lt file_max_size gt This tag configures the maximum size in KB of the files storing the SharedReaderQueue data both metadata and user data Queuing Ser vice will create a new file when this size is exceeded Default 1000 KB
10. lt update_datareader_qos gt Configures the QoS of the DataReader used to receive the status information required by the SharedReaderQueue replication proto col If the tag is not defined Queuing Service will use the Connext defaults with the following changes e reliability kind DDS_RELIABLE_RELIABILITY_QOS this value cannot be changed e history kind DDS KEEP ALL HISTORY OOS this value cannot be changed 0or1 lt update datawriter gos gt Configures the QoS of the DataWriter used to publish the status information required by the SharedReaderQueue replication proto col If the tag is not defined Queuing Service will use the Connext defaults with the following changes e reliability kind DDS_RELIABLE_RELIABILITY_QOS this value cannot be changed e history kind DDS KEEP ALL HISTORY OOS this value cannot be changed 0or1 3 22 XML Tags for Configuring Queuing Service Table 3 15 Queue QoS Tags Tags within lt queue_qos gt Description Number of Tags Allowed lt distribution gt Configures the dispatch policy for the SharedReaderQueue Queuing Service uses the dispatch policy to determine which QueueConsumer gets each sample In this release Queuing Service only supports a ROUND_ROBIN dispatch policy with and without explicit availability feedback from QueueConsumers You can also configure a SharedReaderQueue so that the last sample in the Share dReaderQueue
11. Section 3 3 1 lt queuing_service gt See Configuring Queuing Service Required Section 3 3 2 Table 3 1 Top Level Tags in the Configuration File Tags within sail er adds Description of Tags Allowed ep A A 1 lt queuing_service gt Specifies a Queuing Service configuration See Configuring Queuing Service 4 Or mis Section 3 3 2 reguired Specifies a QoS library and profiles lt qos_library gt The contents of this tag are specified in the same manner as for a Connext ina DDS QoS profile file See Chapter 15 in the RTI Connext DDS Core Libraries User s Manual Defines types that can be used by Oueuing Service See Configuring Queuing a Service Types Section 3 3 1 A 3 3 1 Configuring Queuing Service Types Queuing Service allows users to provide type definitions for a SharedReaderQueue using two different mechanisms LJ Type definition in the XML configuration file L Type discovery 3 4 XML Tags for Configuring Queuing Service To define and use a type in your XML configuration file 1 Define your type within the lt types gt tag This is one of the top level tags see Table 3 1 Top Level Tags in the Configuration File 2 Refer to it using its fully qualified name in the SharedReaderQueues that will use it For example lt xml version 1 0 gt lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti queuing service
12. Share dReaderQueue is delivered to only one of the QueueConsumers L SharedReaderQueueName A string label that uniquely identifies a SharedReader Queue within a DDS domain It is derived from the name of the SharedSubscriber that hosts the queue and the name of the associated DDS Topic as in lt aQueueTopic Name gt lt aSharedSubscriberName gt IJ Session Defines a threaded context for a SharedReaderQueue Sessions are part of SharedSubscribers SharedReaderQueues in different sessions can be processed in paral lel J QueueProducer An application level entity that is either a DDS DataWriter or a wrapper for it which allows an application to send data on a single Topic to a SharedReader Queue 2 1 Paths Mentioned in Documentation J OueueConsumer An application level entity that is either a DDS DataReader or a simple wrapper for it which allows an application to access data on a single DDS Topic from a SharedReaderOueue hosted inside a SharedSubscriber The QueueConsumer DataRead ers compete for the data on the SharedReaderQueue such that each sample in the Shared ReaderQueue will be received by exactly one QueueConsumer DataReader 2 2 Paths Mentioned in Documentation The documentation refers to LJ lt NDDSHOME gt This refers to the installation directory for Connext DDS The default installation paths are e Mac OS X systems Applications rti connext dds version e UNIX based systems non root user h
13. Subscribe Monitoring cmccoconoonononnnananinonacananononononananononononos 3 11 3 3 4 2 1 Publish Subscribe Monitoring Configuration Inheritance 3 12 3 3 4 3 Configuring Statistics Calculation Process ieeesesereeessesseessesesessssssseseess 3 13 3343 11 Statistics Calculation ii ane eea eieaa ieser da 3 14 3 3 5 Configuring Persistence Settings mirrrserssmssmssmisssesmmrmsmmss 3 14 3 3 6 Configuring DomainParticipantS cocicicinonnnonnnnecnenacnnccnnananananononananananononononononononanananononos 3 14 3 3 6 1 Configuring Memory Management for Sample Buffers 0 3 18 3 3 7 Configuring SharedSubscribelS mimica ii 3 18 3 3 8 Configuring Session Settings ccccccssssesceceesescsssnsesesescesenesescenenessseenssesescecesesesesnsnenenees 3 19 3 3 9 Configuring SharedSubscribers Sessions comcnnnnncicnnnnoncnnnnncnnanonnnnnnnanonornrnnanororo non ono ro rannnnnos 3 19 3 3 10 Configuring SharedReaderQueue cocccccooononoconononononcnonanonononcnnannnncnconanannonon cono nano corn orarnninns 3 21 3 3 11 Configuring DeadLetterSharedReaderQueues ccicicioinnnoniononnncnoncnnoronnnnininnorononcincororanananos 3 26 3A Using Variables ir AM A Aoi 3 27 3 5 Enabling RTI Distributed Logger in Queuing SerViCe oocccncnnonncnnnnnnononcnnncnnnnnnnoncncnnananncorncoranncncnoos 3 27 RUNNING QUEUING Service nnnnnnnnnannannnannnnnnnnnnnnnnnnnnaa 4 1 4 1 St
14. Table 3 15 Queue QoS Tags o Its serialized size is smaller than the threshold set with lt domain_participant gt lt memory_management gt lt sample_buffer_min_size gt see Memory Management for a Sample Sec tion 2 15 2 o lt domain_participant gt lt memory_management gt lt sample buffer trim to size gt is false see Memory Management for a Sample Section 2 15 2 Example lt persistence gt lt kind gt PERSISTENT lt kind gt lt in memory state gt true lt in memory state gt lt persistent gt Default e kind VOLATILE e in memory state true See Oueuing Service Persistency Section 2 14 Tags within Number 8 Description of Tags lt queue_qos gt Allowed Configures whether or not the SharedReaderOueue state must be persisted on disk for fault tolerance purposes There are two values for this policy e VOLATILE Keep the samples in memory e PERSISTENT Store the samples into disk Example lt persistence gt lt kind gt PERSISTENT lt kind gt lt persistent gt In the case of PERSISTENT SharedReaderQueues you can choose between two implementations using the XML tag lt in_memory_state gt e Without In Memory State The metadata and user data associated with the SharedReaderQueue s samples is kept only on disk e With In Memory State The metadata for the SharedReaderQueue s samples is always kept both on disk and in memory The sample s user data is kept in lt persistence gt memory a
15. attributes you may set for lt shared_reader_queue gt Table 3 14 SharedReaderQueue Tags Tags within phe aa Description of Tags lt shared_reader_queue gt Allowed Configures the QoS for the SharedReaderQueue DataReader If the tag is not defined Queuing Service will use the Connext DDS defaults with the following changes e reliability kind DDS RELIABLE RELIABILITY OOS this value cannot be changed e reliability acknowledgment kind lt datareader_qos gt APPLICATION_EXPLICIT_ACKNOWLEDGMENT_ MODE Qorl e history kind DDS_KEEP_ALL_HISTORY_QOS this value cannot be changed e reader resource limits max app ack response length 1 e subscription name role name OUEUING SERVICE e service kind OUEUING SERVICE OOS this value cannot be changed Configures the QoS for the SharedReaderQueue DataWriter If the tag is not defined Queuing Service will use the Connext DDS defaults with the following changes e reliability kind DDS_RELIABLE_RELIABILITY_QOS this value cannot be changed e reliability acknowledgment kind Dor1 APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE this value cannot be changed e history kind DDS KEEP ALL HISTORY OOS this value cannot be changed e service kind OUEUING SERVICE OOS this value cannot be changed lt datawriter gos gt Configures the QoS for the SharedReaderQueue See Table 3 15 Queue QoS Tags 0or1 lt queue_qos gt 3 21 XML Tags for Con
16. command line options used to configure remote administration take precedence over the XML configuration Configuring Memory Management for a CommandReply Buffer The lt memory_management gt tag under lt administration gt controls how Queuing Service allo cates memory for the string_body or octet_body buffer in a CommandReply For example lt memory_management gt lt sample buffer min size gt 16000 lt sample buffer min size gt lt sample buffer trim to size gt true lt sample buffer trim to size gt lt memory management gt XML Tags for Configuring Queuing Service Table 3 4 Remote Administration Tags Tags within lt administration gt Description Number of Tags Allowed lt datareader_qos gt Configures the DataReader QoS for remote administration If the tag is not defined Queuing Service will use the Connext DDS defaults with the following changes e reliability kind DDS RELIABLE RELIABILITY OOS this value cannot be changed e history kind DDS KEEP ALL HISTORY OOS e resource limits max samples 32 Oorl lt datawriter_qos gt Configures the DataWriter QoS for remote administration If the tag is not defined Queuing Service will use the Connext DDS defaults with the following changes e history kind DDS_KEEP_ALL_HISTORY_QOS e resource limits max samples 32 0or1 lt distributed logger gt Configures RTI Distributed Logger See Enabling RTI Distributed Log g
17. count unsigned long long high watermark count change unsigned long long low watermark count change unsigned long long gueue full count change Extensibility MUTABLE EXTENSIBILITY Where L high watermark count Number of times that the SharedReaderQueue went over the high watermark since the service started LJ low_watermark_count Number of times that the SharedReaderQueue went below the low watermark since the service started I high watermark count change Number of times that the SharedReaderQueue has gone over the high watermark since the last remote administration command to retrieve the status of the SharedReaderOueue L low watermark count change Number of times that the SharedReaderQueue has gone below the low watermark since the last remote administration command to retrieve the status of the SharedReaderOueue Notice that it is also possible to monitor how many times the SharedReaderOueue filled up by inspecting the fields gueue full countand gueue full count change Sample Replacement Policy The tag lt replacement_policy gt under lt shared_reader_queue gt lt queue_qos gt lt resource_limits gt can be used to configure a SharedReaderQueue behavior when it is full and a new sample is received For example lt resource limits gt lt replacement policy gt lt kind gt REJECT WITHOUT REPLACEMENT lt kind gt lt replacement policy gt lt resource_limits gt In the above example a new incoming sa
18. for a OueueConsumer is marked with the flag DDS LAST SHARED READER OUEUE SAMPLE before is sent to the Queue Consumer The QueueConsumer application can inspect the value of this flag by checking the flag field in Samplelnfo Example lt distribution gt lt kind gt ROUND_ROBIN lt kind gt lt mark_last_undelivered_sample gt true lt mark_last_undelivered_sample gt lt property gt lt value gt lt element gt lt name gt UNACKED THRESHOLD lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt value gt lt element gt lt name gt ALLOW CONSUMER FEEDBACK lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt lt distribution gt See Selecting a QueueConsumer for a Sample Section 2 10 for more information regarding the dispatch policy Defaults e kind ROUND ROBIN e UNACKED_THRESHOLD 1 e ALLOW CONSUMER FEEDBACK 0 e mark last undelivered sample false 0or1 lt lifespan gt Configures how long a sample written by a OueueProducer is kept in the SharedReaderOueue Example lt lifespan gt lt duration gt lt sec gt 60 lt sec gt lt nanosec gt 0 lt nanosec gt lt duration gt lt lifespan gt Note A finite lifespan set on the QueueProducer s DataWriter using the Lifespan QoS policy takes precedence over this value Default UNLIMITED no lifespan Oorl 3 23 XML Tags for Configuring Queuing Service
19. lt dead letter shared reader gueue gt lt shared reader gueue session Session 1 dead letter gueue DeadLetter 1 gt lt topic name gt HelloWorld lt topic name gt lt type name gt Foo lt type names lt reply type gt Bar lt reply type gt lt queue_qos gt lt distribution gt 3 2 XML Syntax and Validation lt kind gt ROUND ROBIN lt kind gt lt distribution gt lt lifespan gt lt duration gt lt sec gt 120 lt sec gt lt nanosec gt 0 lt nanosec gt lt duration gt lt lifespan gt lt redelivery gt lt reponse_timeout gt lt duration gt lt sec gt 10 lt sec gt lt nanosec gt 0 lt nanosec gt lt duration gt lt reponse timeout gt lt max delivery retries gt 10 lt max delivery retries gt lt redelivery gt lt queue_qos gt lt shared reader gueue gt lt shared subscriber gt lt domain participant gt lt gueuing service gt lt dds gt 3 2 XML Syntax and Validation The XML configuration file must follow these syntax rules 4 The syntax is XML the character encoding is UTF 8 L Opening tags are enclosed in lt gt closing tags are enclosed in lt gt I A tag value is a UTF 8 encoded string Legal values are alphanumeric characters Queu ing Service s parser will remove all leading and trailing spaces from the string before it is processed For example lt tag gt value lt tag gt is the same as lt tag gt value lt tag gt J All values are case se
20. out the type representation information 3 5 XML Tags for Configuring Queuing Service 3 3 2 Configuring Queuing Service A configuration file must have at least one lt queuing_service gt tag which is used to configure an execution of Queuing Service A configuration file may contain multiple lt queuing_service gt tags When you start Queuing Service you can specify which lt queuing_service gt tag to use to config ure the service using the cfgN ame command line parameter For example lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti queuing service xsd gt lt queuing service name QueuingService 1 gt lt gueuing service gt lt gueuing Service name QueuingService_2 gt lt gueuing service gt lt dds gt Starting Queuing Service with the following command will use the lt queuing_service gt tag with the name QueuingService_1 Queuingservice cfgFile example xml cfgName QueuingService 1 Because a configuration file may contain multiple lt queuing_service gt tags one file can be used to configure multiple Queuing Service executions Table 3 2 Queuing Service Tags describes the tags allowed within a lt queuing_service gt tag Notice that the lt domain_participant gt tag is required lt queuing_service gt Optional lt domain_participant gt Required 3 6 XML Tags for Configuring Queuing Service Table 3 2 Queuing Service
21. resource xml RTI_LQUEUING_SERVICE xml This configuration contains a service running with an empty SharedSubscriber with remote administration and monitoring enabled If you want to start Queuing Service with different parameters you can use the utility nssm You can specify the parameters from the command line by setting the option AppParameters For example you would enter this all on one line SNDDSHOMES resource app bin x64Win64VS2008 nssm exe set lt serviceName gt AppParameters lt queuing service arguments gt For more information and examples see Notes when Running as a Windows Service Section 4 3 3 Additionally you can start Queuing Service from the Windows Services Control Manager From the Start Menu select Control Panel Administrative Services Services Click on the service in the list then right click to select Start Notes when Running as a Windows Service Here are some things to consider when running Queuing Service as a Windows Service L All AppParameters arguments must be enclosed in quotation marks 1 To refer to variables in the XML configuration file use the Queuing Service command line option var to set the variable s value The syntax for referring to a variable in the XML file is lt name gt NAME lt name gt 4 4 Using Queuing Service as a Windows Service 4 3 4 4 3 5 L For the AppParameters passed to nssm use var like this var MY_DOMAIN 10 For example you would e
22. sample The initial and maximum number of buffers in the pool as well as the pool s growth pol icy is configured using the XML tag lt resource_limits gt under lt shared_reader_queue gt lt queue_qos gt When the serialized size of the incoming sample is greater than this value Queuing Ser vice will allocate the buffer from the heap dynamically upon sample reception L sample_buffer_trim_to_size This value controls what to do with the buffers that are dynamically allocated When true the buffers will be released when the corresponding samples are remove from the SharedReaderQueues When false the buffers are kept around for future samples They maybe released later on but only to be replaced by big ger buffers Ranges L sample_buffer_min_size 1 In a SharedReaderQueue is the maximum serialized size of its samples or positive number L sample_buffer_trim_to_size true or false Defaults L sample buffer min size 256 L sample buffer trim to size true Notice that setting a positive value for sample buffer min size is critical when a data type has a very high maximum serialized size e g megabytes but most of the samples sent are much smaller than the maximum possible size e g kilobytes In this case the memory footprint is reduced dramatically while still correctly handling the rare cases in which very large samples are published Configuring SharedSubscribers SharedSubscribers are containers
23. service will remove samples on the FailedDelivery state from disk 4 The service will remove samples on the Delivered state from disk L The service will move samples in the Assigned Sent Rejected or Timed out state to the Enqueued state SharedReaderQueue Resource Management Queuing Service provides fine grained control over the resources memory and disk associated with the samples in a SharedReaderQueue It provides ways to monitor when the space taken by the samples in a SharedReaderQueue goes above or below configurable watermarks and when the SharedReaderQueue fills up Finally it also provides a way to configure the Share dReaderQueue behavior when a new sample arrives and the SharedReaderQueue is full Maximum SharedReaderQueue Size The maximum size of a SharedReaderQueue can be configured based on number of samples number of bytes in memory or both Initial and Maximum Number of Samples The tag lt resource_limits gt under lt shared_reader_queue gt lt queue_qos gt can be used to config ure the initial and maximum number of samples in a SharedReaderQueue see Table 3 15 Queue QoS Tags as well as if dynamic allocations are allowed and how they occur Example SharedReaderQueue Resource Management 2 15 1 2 lt resource limits gt lt queue_allocation_settings gt lt initial count gt 10 lt initial count gt lt max count gt LENGTH UNLIMITED lt max count gt lt incremental count gt 1 lt incre
24. target queuing services data Return Value Upon success this command returns RTI SERVICE COMMAND REPLY OK in the retcode field of the reply The ServiceData is sent in serialized form within the field octet_body in the CommandReply If there is an error this command returns RTI SERVICE COMMAND REPLY ERROR and the field string body contains a human read able string describing the error Service Data The type of the ServiceData can be found in the file lt NDDSHOME gt resource idl QueuingSer viceTypes idl struct SharedReaderQueueData Fully qualified name of the SharedReaderQueue within the XML file string lt NAME MAX LENGTH gt queue_name key string lt NAME MAX LENGTH gt topic_name Extensibility MUTABLE_EXTENSIBILITY struct ServiceData sequence lt SharedReaderQueueData gt shared reader queue data list Extensibility MUTABLE EXTENSIBILITY To deserialize the ServiceData from the CommandReply octet body use the following opera tions IJ C ServiceDataTypeSupport_deserialize_data_from_cdr_buffer I C ServiceDataTypeSupport deserialize_data_from_cdr_buffer I C CLI ServiceDataTypeSupport deserialize data from cdr buffer LJ C ServiceDataTypeSupport deserialize data from cdr buffer I Java ServiceDataTypeSupport get instance deserialize from cdr buffer When generating code for QueuingServiceTypes idl in C C and NET make sure you use the unbounded
25. this software and associated documentation files the Software to deal in the Software without restriction including without limitation the rights to use copy modify merge publish distribute sublicense and or sell copies of the Software and to permit persons to whom the Software is furnished to do so subject to the following conditions The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software THE SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM DAMAGES OR OTHER LIABILITY WHETHER IN AN ACTION OF CONTRACT TORT OR OTHERWISE ARISING FROM OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE Technical Support Real Time Innovations Inc 232 East Java Drive Sunnyvale CA 94089 Phone 408 990 7444 Email support rti com Website https support rti com Contents Welcome to RTI Queuing Service 10nanannennnnenennen na 1 1 2 Queuing Service Architecture and Operation 2 1 2 1 Terms to 9 2107 Wisin iii 2 1 2 2 Paths Mentioned in Documentation cccccccsecssesseesscescesscescessecsesseecesceeeecsecssecsecssesasceeseseeeeseeseaeeae
26. to remove the data from the ReaderQueue in which case a subse quent read take will not see that sample Two threads can read take from the same DataReader to balance the load of processing samples from the queue However each DataReader has a dif ferent ReaderQueue therefore they are independent from each other Taking from one DataReader does not affect the other DataReaders Queuing Service provides a way to share a ReaderQueue SharedReaderQueue among DataRead ers of the same Topic see Figure 2 1 running in separate processes possibly on different com puters By sharing the same ReaderQueue multiple DataReaders can collaborate coordinate and load balance among each other 2 3 DataWriter Connection to a Shared ReaderOueue Figure 2 1 2 4 Load Balancing Using Aueuing Service Queuing Service Shared Subscriber ms RR DW DataWriter DR DataReader Realizing the SharedReaderQueue in a separate service also decouples the lifecycle of the sam ples from that of the producer DataWriter and consumer DataReader of the data In order to be shared a ReaderOueue must have a ReaderQueueName so that a DataReader can specify which queue to attach to Queuing Service provides a way to host the SharedReaderQueues DataReaders attach to a shared ReaderQueue by specifying the same ReaderQueueName Multiple DataReaders can attach to the same shared ReaderQueue and Queuing Servic
27. 0 Table 3 10 DomainParticipant Tags Tags within SN Number lt domain_participant gt bhosca a of igs Allowed lt domain id gt Specifies the domain ID associated with the DomainParticipant 1 A reguired Controls how to allocate the memory for a sample buffer lt memory management gt For details see Configuring Memory Management for Sample Buffers Oorl Section 3 3 6 1 ats Configures the DomainParticipant QoS If the tag is not defined Queu Ka aka id ing Service will use the Connext DDS defaults Gort Configures a SharedSubscriber See Configuring SharedSubscribers 1 or more lt shared_subscriber gt E Section 3 3 7 required 3 17 XML Tags for Configuring Oueuing Service 3 3 6 1 3 3 7 Configuring Memory Management for Sample Buffers For every sample in a SharedReaderQueue Queuing Service uses a buffer to store the content of the sample in serialized form with CDR representation The lt memory_management gt tag con trols how to allocate the memory for a sample buffer For example memory management gt lt sample buffer min size gt 16000 lt sample buffer min size gt sample buffer trim to size gt true lt sample buffer trim to size gt lt memory management gt L sample buffer min size If the serialized size of an incoming sample is smaller or equal to this value Queuing Service will use a pre allocated buffer with size equal to this value from a pool to hold the
28. 0 1 State Transitions State s Transition Event to Next State Next State Queuing Service sends the sample to the designated Queue Consumer If the sample is the last sample in the SharedReaderQueue Assigned that can be received by the QueueConsumer Queuing Service Sent can be configured to mark the sample with the flag DDS LAST SHARED READER OUEUE SAMPLE You can inspect the status of this flag in a received sample by inspecting the flag field in the Samplelnfo Queuing Service receives an AppAck message from Queue Consumer indicating successful processing Sent In addition if SharedReaderOueue replication is enabled Delivered the delivery of the sample must is communicated to the rep licas Engueued WHEN Queuing Service receives an AppAck message from Queue APT OS O ae MAX_ATTEMPTS Sent Consumer indicating sample rejection AR tedDeli Count ie tele FailedDelivery WHEN Ss daa ee i ala i AttemptedDeliveryCount MAX ATTEMPTS Engueued WHEN Queuing Service does not receive an AppAck message after a AttemptedDeliveryCount lt E timeout MAX_ATTEMPTS i DDS REDELIVERED SAMPLE is set FailedDelivery WHEN AttemptedDeliveryCount is incremented AttemptedDeliveryCount MAX ATTEMPTS Any state The lifespan timeout elapses Expired Selecting a QueueConsumer for a Sample Queuing Service implements the logic that decides which QueueConsumer gets each sample This decision can be made accordi
29. 00 bytes Notice that if the SharedReaderQueue does not have any samples and the size of a new sample exceeds 1 000 000 bytes this sample will be stored in the Share dReaderQueue Therefore it is possible to go beyond 1 000 000 bytes when the SharedReader Queue is empty The configuration parameter max_in_memory_bytes includes both the sample metadata and the sample user data The parameter does not take into account the SharedReaderQueue meta data and the preallocated samples metadata and user data that are not currently used If both lt max_count gt and lt max in memory bytes gt are set to a finite number the maximum size of the SharedReaderOueue will be limited by the limit that is reached first lt max in memory bytes gt is ignored for PERSISTENT SharedReaderOueues where the state is not kept in memory Ranges 2 21 SharedReaderQueue Resource Management 2 15 2 2 15 3 L max in memory bytes LENGTH UNLIMITED or positive number Defaults LJ max in memory bytes LENGTH UNLIMITED Memory Management for a Sample For every sample in a SharedReaderQueue Queuing Service will use a buffer to store the content of the sample in serialized form The memory for that buffer may come from a pre allocated pool of buffers or may be dynamically allocated from the heap upon sample reception This behavior is controlled per lt domain_participant gt using the XML tag lt memory_management gt see Table 3 10 DomainPartici
30. 004 Configuration replication AS sync port WAN port 16000 to 192 168 5 11 16000 WAN port 16001 to 192 168 5 11 16001 WAN port 15002 to 15005 16005 192 168 5 11 15002 WAN port 15003 to 192 168 5 11 15003 WAN port 15004 to 192 168 5 11 15004 WAN port 15005 to 192 168 5 11 15005 WAN port 16002 to 192 168 5 11 16002 WAN port 16003 to 192 168 5 11 16003 WAN port 16004 to 192 168 5 11 16004 WAN port 16005 to 192 168 5 11 16005 NDDS DISCOVERY PEERS tcpv4 lan 192 168 5 12 16001 tcpv4 lan 192 168 5 12 16003 tcpv4 lan 192 168 5 12 16005 tcpv4 lan 192 168 5 11 15003 NDDS DISCOVERY PEERS tcpv4 lan 192 168 5 11 15001 tcpv4 lan 192 168 5 11 15003 tcpv4 lan 192 168 5 11 15005 tcpv4 lan 192 168 5 12 16003 Remote Admin Producer Consumer NDDS DISCOVERY PEERS tepv4_wan 18 181 0 32 15002 tcpv4 wan 18 181 0 32 16002 tepv4_wan 18 181 0 32 15004 tcpv4 wan 18 181 0 32 16004 J NDDS_DISCOVERY_PEERS tcpv4 wan 18 181 0 32 15000 tepv4_wan 18 181 0 32 16000 i NDDS_DISCOVERY_PEERS tcpv4_wan 18 181 0 32 15000 tcpv4 wan 18 181 0 32 16000 In a basic scenario that does not include configuration replication a Queuing Service instance cre ates two DomainParticipants 1 The first DomainParticipants is used to communicate with QueueProducers and Queue Consumers This DomainParticipants is also used to exchange SharedRead
31. 181 0 32 15001 lt value gt lt element gt lt value gt lt property gt lt participant_qos gt lt administration gt lt domain participant name DomainParticipant gt lt domain id gt 0 lt domain id gt lt participant goSs gt lt property gt lt value gt lt element gt lt name gt dds transport tcp server bind port lt name gt lt value gt 15000 lt value gt lt element gt lt element gt lt name gt dds transport tcp public address lt name gt lt value gt 18 181 0 32 15000 lt value gt lt element gt lt value gt lt property gt lt participant_qos gt lt domain_participant gt lt gueuing services The following XML snippet shows how to configure the applications running outside the NAT lt participant_qos gt lt property gt lt value gt lt element gt lt name gt dds transport load plugins lt name gt lt value gt dds transport tcp lt value gt lt element gt lt element gt lt name gt dds transport tcp library lt name gt lt value gt nddstransporttcp lt value gt lt element gt lt element gt lt name gt dds transport tcp parent classid lt name gt lt value gt NDDS TRANSPORT CLASSID TCPV4 WAN lt value gt lt element gt lt element gt lt name gt dds transport tcp create function lt name gt lt value gt NDDS Transport TCPv4 create lt value gt lt element gt lt element gt lt name gt dds transport tcp server bind port lt name gt lt value gt 0 lt value gt
32. 4 2 1 Publish Subscribe Monitoring Configuration Inheritance The lt status publication period gt defined under lt gueuing service gt lt monitoring gt is inher ited by all the monitorable entities An entity can override this value using the lt entity_monitoring gt tag For example this how a SharedReaderQueue would override the status publication period lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti gueuing service xsd gt lt queuing service name OueuingService 1 gt lt monitoring gt lt domain_id gt 55 lt domain_id gt lt status_publication_period gt lt sec gt 5 lt sec gt lt nanosec gt 0 lt nanosec gt lt status_publication_period gt lt monitoring gt lt domain participant name DomainParticipant 1 gt lt shared subscriber name SharedSubscriber 1 gt lt shared reader gueue name SharedReaderQueue 1 session Session 1 gt lt entity monitoring gt lt enabled gt true lt enabled gt lt status publication period gt lt sec gt 3 lt sec gt lt nanosec gt 0 lt nanosec gt lt status publication period gt lt entity monitoring gt lt shared reader gueue gt lt shared subscriber gt 3 12 XML Tags for Configuring Oueuing Service lt domain participant gt lt gueuing service gt lt dds gt In the above example the SharedReaderQueue overrides the status publication period setting it to 3 seconds Table 3 6 Entity M
33. HISTORICAL METRICS gt historical metrics The count is the sum of all values received during the time frame For example in the case of engueue throughput count is the number of samples engueued during the time frame 3 13 XML Tags for Configuring Queuing Service 3 3 4 3 1 3 3 5 3 3 6 Oueuing Service always calculates the statistics corresponding to the time between two status publications publication period metrics field independently of whether or not publish sub scribe monitoring is enabled This time is configured using the tag lt status publication period gt under lt monitoring gt or lt entity_monitoring gt Configuring Publish Subscribe Monitoring Sec tion 3 3 4 2 You can also select additional windows on a per entity basis using the tag lt historical statistics gt under lt statistics gt see Statistics Calculation Section 3 3 4 3 1 The sequence historical metrics in StatisticVariable contains values corresponding to the windows that have been enabled L 5 sec metrics correspond to activity in the last five seconds L 1 min metrics correspond to activity in the last minute 1 5 min metrics correspond to activity in the last five minutes l 1 hour metrics correspond to activity in the last hour L Up time metrics correspond to activity since the entity was created Each window has a field called period_ms that identifies its size in milliseconds For the publication_period_metrics th
34. I OUEUING SERVICE xml defines a service with an empty SharedSubscriber and with administration enabled L lt working directory gt USER_QUEUING_SERVICE xml This file is loaded automatically if it exists LJ File specified using the command line parameter cfgFile The command line option cfgFile see Table 4 1 RTI Queuing Service Command Line Options can be used to specify a configuration file An example configuration file is seen below You will learn the meaning of each line as you read the rest of this chapter Example XML Configuration File lt xml version 1 0 gt lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti queuing service xsd gt lt types gt lt struct name Foo gt lt member type string stringMaxLength 255 name message gt lt struct gt lt struct name Bar gt lt member type string stringMaxLength 255 name message gt lt struct gt lt types gt lt queuing service name QueuingService 1 gt lt administration gt lt domain_id gt 56 lt domain_id gt lt administration gt lt domain participant name DomainParticipant 1 gt domain id gt 57 lt domain id gt lt shared subscriber name SharedSubscriber 1 gt lt session_settings gt lt session name Session_1 gt lt session_settings gt lt dead letter shared reader gueue name DeadLetter 1 session Session 1 gt lt topic name gt DeadLetter lt topic name gt
35. L file Specifies a name prefix to use with all files created by Queuing Service persistentFilePrefix This option overrides the value of the tag lt file prefix gt within lt persistence_settings gt lt filesystem gt Default Value in lt persistence_settings gt lt filesystem gt lt file_prefix gt persistentStoragePath Configures the directory for persistent storage This option overrides the value of the tag lt directory gt within lt persistence_settings gt lt filesystem gt Default Value in lt persistence_settings gt lt filesystem gt lt directory gt var lt name gt lt value gt Sets the value of the variable lt name gt This variable can be referenced within the XML configuration files using the lt name gt notation See Sec tion 3 4 Using Variables in XML in the Queuing Service User s Manual for more information on configuration variables You may have more than one var flag on the command line On Windows platforms you will need to put quotation marks around the variable name and value like this var MY VAR myvalue verbosity lt n gt Controls what type of messages are logged 0 Silent 1 Exceptions Connext DDS and Queuing Service default 2 Warnings Queuing Service 3 Information Queuing Service 4 Warnings Connext DDS and Queuing Service 5 Tracing Queuing Service 6 Tracing Connext DDS and Queuing Service Each verbosity level n inclu
36. PLibrary TCPProfile gt 9 5 Asymmetric TCP Communication with Oueuing Service And Replication lt property gt lt value gt lt element gt lt name gt dds transport tcp server bind port lt name gt lt value gt 15002 lt value gt lt element gt lt element gt lt name gt dds transport tcp public address lt name gt lt value gt 18 181 0 32 15002 lt value gt lt element gt lt element gt lt name gt dds transport tcp2 server bind port lt name gt lt value gt 15003 lt value gt lt element gt lt element gt lt name gt dds transport tcp2 public address lt name gt lt value gt 192 168 5 11 15003 lt value gt lt element gt lt value gt lt property gt lt participant_qos gt lt administration gt lt service qos gt lt configuration replication gt lt participant gos base name TCPLibrary TCPProfile gt lt property gt lt value gt lt element gt lt name gt dds transport tcp server bind port lt name gt lt value gt 15004 lt value gt lt element gt lt element gt lt name gt dds transport tcp public address lt name gt lt value gt 18 181 0 32 15004 lt value gt lt element gt lt element gt lt name gt dds transport tcp2 server bind port lt name gt lt value gt 15005 lt value gt lt element gt lt element gt lt name gt dds transport tcp2 public address lt name gt lt value gt 192 168 5 11 15005 lt value gt lt element gt lt value gt lt property gt l
37. Persistency 2 14 2 Oueuing Service instances the configuration can be changed at run time by sending remote com mands to the service see Chapter 5 Administering Oueuing Service from a Remote Location For example you may decide to add a new SharedReaderOueue or to remove a SharedReader Oueue You can choose to persist the configuration to disk each time it changes by setting the lt kind gt tag within lt gueuing service gt lt service gos gt lt persistence gt to PERSISTENT see Table 3 15 Queue QoS Tags The location of the file where the configuration is persisted as well as the properties of the stor age process can be configured using the lt filesystem gt tag under lt queuing_service gt lt persistence_settings gt see Configuring Persistence Settings Section 3 3 5 When Queuing Service is restarted it will look for its persisted configuration using the following values L Command line option appName see Queuing Service runs as a separate application The script to run the executable is in lt NDDSHOME gt bin There are four ways to start Queuing Service Section L XML tag values lt directory gt and file prefix gt under lt persistence_settings gt lt filesys tem gt If the persisted configuration is found and the service is configured from a XML file the per sisted configuration will be used to configure the service instance In that case the input XML file is only used to find the loc
38. RTI Queuing Service User s Manual Version 5 2 0 t Your systems Working as one O 2014 2015 Real Time Innovations Inc AII rights reserved e Printed in U S A First panie June 2015 Trademarks Real Time Innovations RTI NDDS RTI Data Distribution Service DataBus Connext Micro DDS the RTI logo 1RTI and the phrase Your Systems Working as one are registered trademarks trademarks or service marks of Real Time Innovations Inc All other trademarks belong to their respective owners Copy and Use Restrictions No part of this publication may be reproduced stored in a retrieval system or transmitted in any form including electronic mechanical photocopy and facsimile without the prior written permission of Real Time Innovations Inc The software described in this document is furnished under and subject to the RTI software license agreement The software may be used or copied only under the terms of the license agreement Third Party Copyright Notices Portions of this product were developed using libxml2 http xmlsoft org and lixslt http xmlsoft org libxslt which are licensed under the MIT license http opensource org licenses mit license html The MIT License MIT libxml2 Copyright C 1998 2012 Daniel Veillard All Rights Reserved libxslt Copyright C 2001 2002 Daniel Veillard All Rights Reserved Permission is hereby granted free of charge to any person obtaining a oT of
39. State In this mode the metadata for the SharedReaderQueue s sam ples is always kept both on disk and in memory The sample s user data is kept in mem ory and on disk only when Oueuing Service Persistency e Its serialized size is smaller than the threshold set using the tag lt domain participant gt lt memory management gt lt sample buffer min size gt see Memory Management for a Sample Section 2 15 2 e domain participant gt lt memory management gt lt sample buffer trim to size gt is set to to false see Memory Management for a Sample Section 2 15 2 PERSISTENT SharedReaderOueues with in memory state introduce significant performance improvements because the sample metadata and in some cases the sample user data does not need to be accessed from disk The disadvantage is that the number of samples on the Share dReaderOueue is limited by the available memory as the service needs to keep some state per sample in memory To configure a PERSISTENT SharedReaderOueue to keep the sample state in memory the default configuration you must set the XML tag lt in memory state gt under lt gueue gos gt lt persistence gt to true Samples are persisted before Oueuing Service sends an application level acknowledgement AppAck message to the OueueProducer DataWriter indicating successful processing of the sample Like with the service configuration the location of the file s where the SharedReaderOueue s sample
40. Support command line option 5 7 Remote Commands in Oueuing Service 5 4 6 Get Samples From a SharedReaderQueue The following command is used to get one or more samples from the SharedReaderOueue using a condition This is a multi reply command in which the number of responses is egual to the number of samples satisfying the condition GET lt target gueuing service gt lt shared reader gueue resource identifier gt mes sage lt sample selector gt Parameters The lt sample selector gt see Sample Selector Section 5 2 2 is a SOL expression that specifies the set of samples that must be retrieved This expression must be provided in the field string body of the CommandRequest Return Value Upon success this command returns X number of replies where X is the number of samples in the SharedReaderOueue satisfying the lt sample selector gt expression In each one of these replies the retcode field is set to RTI SERVICE COMMAND REPLY OK and the octet body is initialized with the serialized sample in CDR format If there are no samples satisfying the lt sample_selector gt the service returns one reply where the retcode field is set to RTI SERVICE COMMAND REPLY OK and the octet body is empty In multi reply commands you can detect the last reply for a given command by inspecting the field flag in DDS Samplelnfo For intermediate replies the flag DDS INTERMEDIATE REPLY SEOUENCE SAMPLE is set In the last reply th
41. Tags Tags within lt gueuing service gt Description Number of Tags Allowed lt administration gt Enables and configures remote administration See Configuring Adminis tration Section 3 3 3 and Chapter 5 Administering Oueuing Service from a Remote Location Oorl lt domain_participant gt For each lt domain_participant gt tag Queuing Service creates one Domain Participant to communicate over DDS SharedSubscribers are defined within a lt domain_participant gt See Configuring DomainParticipants Section 3 3 6 1 or more required lt monitoring gt Enables and configures general remote Pub Sub monitoring See Configuring Monitoring Section 3 3 4 Oorl lt persistence_settings gt Configures the storage settings that are used to persist the service state as well as the SharedReaderQueues samples See Configuring Persistence Settings Section 3 3 5 Oorl lt replication_settings gt Configures the default settings for the replication protocol for Share dReaderQueues and configuration These settings can be overridden by the settings under e lt shared reader gueue replication gt under lt service_qos gt e lt configuration_replication gt under lt service_qos gt e lt replication gt under lt queue_qos gt Important Using this tag does not enable replication To enable replica tion set e lt shared_reader_queue_replication gt under lt service_qos gt
42. a lt shared_reader_queue_replication gt tag You can also replicate individual SharedReaderQueues by using the lt replication gt tag under lt shared_reader_queue gt lt queue_qos gt see Table 7 2 Replication Tags SharedReaderQueue Replication Tags oe Number Tags within D zaii fT lt shared_reader_queue_replication gt socn pian oi BS Allowed Enables disables replication for all Share dReaderOueues in the service lt enabled gt You can override this behavior on a per Share 0or1 dReaderQueue basis by setting lt replication gt under lt shared reader gueue gt lt gueue gos gt Default true Configures the replication protocol See Table 7 3 Replication Settings Tags lt replication_settings gt Default If not set replication settings are inher 0 or 1 ited from the settings in lt replication_settings gt under lt queuing_service gt Replication Tags Tags within lgi ps lt replication gt Description of Tags Allowed Enables disables replication for the SharedReaderOueue lt enabled gt 0or1 Default true Configures the replication protocol See Table 7 3 Replication Settings Tags Default If not set replication settings are inherited as follows lt replication settings gt First from the settings in lt replication_settings gt under 9 or1 lt gueuing service gt lt service gos gt lt shared reader gueue replication gt Second from the settings in lt repl
43. a_from_cdr_buffer LJ C FooTypeSupport deserialize_data_from_cdr_buffer I Java FooTypeSupport get instance deserialize from cdr buffer LJ C CLI FooTypeSupport deserialize data from cdr buffer L C FooTypeSupport deserialize data from cdr buffer For additional information on these deserialization operations see the Connext DDS API Refer ence HTML documentation The undelivered reason is an enumeration describing why the sample was not delivered There are two possible reasons LJ The lifespan expired for the sample L The sample exceeded the maximum number of redelivery retries For more information on why a sample may be undelivered see Sample Lifecycle In Queuing Service Section 2 9 By default SharedReaderQueues do not send undelivered samples to the dead letter queue To enable this behavior you must use the attribute dead letter gueue in the lt shared_reader_queue gt tag This attribute must be set to the name of the dead letter queue in the configuration file 2 16 Detecting the Presence of a SharedReaderQueue 2 13 2 14 Detecting the Presence of a SharedReaderQueue You can detect the existence of a SharedReaderQueue for a given QueueProducer or QueueCon sumer by monitoring the matched subscriptions associated with the QueueProducer s DataW riter and the matched publications associated with the QueueConsumer s DataReader The PublicationBuiltinTopicData and Subscrip
44. able in Queuing Service Accessing Queuing Service from a Connext DDS application Section 5 5 explains how to use remote administration from a Connext DDS application 5 4 1 Create SharedReaderQueue The following command is used to create a SharedReaderQueue CREATE target gueuing services lt shared subscriber resource identifier gt lt xml url gt Where Lj lt shared_subscriber_resource_identifier gt is the resource identifier for the SharedSubscriber that will contain the SharedReaderQueue 1 lt xml_url gt contains an XML snippet containing the SharedReaderQueue configuration A full file starting with lt dds gt is not valid For example str lt shared_reader_queue name SharedReaderQueue_1 gt lt topic name gt ReguestMessageTopic lt topic name gt lt shared reader gueue gt Return Value Upon success this command returns RTI SERVICE COMMAND REPLY OK in the retcode field of the reply Otherwise this command returns one of the following values and the field string body contains a human readable string describing the error L RTI SERVICE COMMAND REPLY ALREADY EXISTS If the SharedReaderOueue already exists with a different configuration 5 5 Remote Commands in Oueuing Service 5 4 2 5 4 3 5 4 4 L RTI SERVICE COMMAND REPLY DUPLICATED If the SharedReaderQueue already exists with the same configuration LI RTI SERVICE COMMAND REPLY ERROR For any other creation er
45. alls may be involved The next sections explain how to configure and use the TCP transport to communicate with Queuing Service in some typical scenarios Asymmetric TCP Communication With Queuing Service In this scenario Queuing Service is behind a NAT Firewall and the QueueProducers QueueCon sumers and Remote Administration applications run outside the NAT TCP connections can be initiated only by applications running outside the NAT Figure 9 1 shows how to configure the system to communicate using the TCP transport Notice that it is not necessary to set NDDS_DISCOVERY_PEERS in the Queuing Service instance because the connections are initiated from the applications running outside the NAT In this example Queuing Service instantiates two instances of the TCP transport one for administration and one for SharedReaderQueue traffic Each instance uses a separate TCP port 9 1 Asymmetric TCP Communication With Queuing Service Figure 9 1 Asymmetric TCP Configuration QS Instance 1 Private IP address 192 168 5 11 Producer Consumer port 15000 WAN IP address 18 181 0 32 Administration port 15001 Port forward settings NDDS_DISCOVERY_PEERS WAN port 15000 to 192 168 5 11 15000 lt Empty gt WAN port 15001 to 192 168 5 11 15001 Producer Consumer App Remote Admin App NDDS_DISCOVERY_PEERS NDDS DISCOVERY PEERS tcpv4 wan 18 181 0 32 15000 tepv4_wan 18 181 0 32 15001 The following XML snippet shows h
46. amples from a SharedReaderQueue For more information on remote administration see Chapter 5 Administering Oueuing Service from a Remote Location Queuing Service Monitoring With Queuing Service you can monitor the status of the service and its SharedReaderQueues using request reply or publish subscribe communication patterns Request reply monitoring is done by issuing remote administration commands that retrieve the status of the different entities in the service See Chapter 5 Administering Queuing Service from a Remote Location Publish subscribe monitoring is done by subscribing to monitoring topics See Chapter 6 Pub lish Subscribe Monitoring of Queuing Service from a Remote Location 2 25 Chapter 3 Configuring Queuing Service 3 1 This chapter describes how to configure Queuing Service For installation instructions please see the Queuing Service Getting Started Guide Queuing Service is configured using a configuration in XML format There are three different ways to provide the initial configuration to Queuing Service L Configuration file The file s can be implicit or explicit using the cfgFile command line option see How to Load the XML Configuration from a File Section 3 1 LJ Database The Queuing Service configuration can be persisted and restored from disk by enabling service state Persistency see Service State Persistency Section 2 14 1 L Remote configuration Queuing Service can be set up to
47. and there is no space for it in the Share dReaderOueue s DataReader cache the sample will be rejected by Connext DDS The OueuePro ducer s DataWriter will not be able to mark that sample or any subseguent samples as acknowledged and eventually it will block after its send window fills up High Availability For high availability you can configure Queuing Service to replicate both the content of the SharedReaderOueues and the service configuration By default SharedReaderOueues within a Oueuing Service instance are not replicated Share dReaderOueues can optionally be replicated across multiple instances of Queuing Service run ning on the same or different nodes By default the service configuration is not replicated The service configuration can optionally be replicated across multiple instances of Queuing Service running in the same or different nodes For more information on SharedReaderOueues and service configuration replication see Chapter 7 High Availability Remote Administration You can control Oueuing Service remotely by sending commands through a special topic Any Connext application can be implemented to send these commands and receive their correspond ing responses These remote administration commands will allow you to LJ Create SharedReaderQueues 3 Delete SharedReaderQueues LJ Flush SharedReaderQueues LJ Get SharedReaderQueues status LJ Get service data Queuing Service Monitoring 2 18 L Get s
48. annnncncononannoncnnonororo ronca narnia 2 22 2 15 3 High and Low WatermarkS ooocncicicinionnnnnnncnnonococnnncononanncnnnnonarorornn coro ro ran nn noro ro ran cion rornn cnn 2 22 2 15 4 Sample Replacement Policy ocncncnnnononinnnnnnnnnnnnnonocononorononononororonononorororon deed a ran craneo 2 23 2 16 High Availability ii A aa E E ias a ais 2 24 2 17 Remote AdministratioN Canta id ia 2 24 2 18 Queuing Service Monitoring sssri aee EE nu kose e trar codiciada cia 2 25 Configuring QUEUING Service 11020nnnanannnnnnnnnennnaa 3 1 3 1 How to Load the XML Configuration from a File m wtsnenennenenensnenenenenneneresnenenee 3 1 3 2 XML Syntaxa d Validation snenge ste ead og a t tanke e te a iee e aaa e ae ei 3 3 3 3 XML Tags for Configuring Queuing Service sss sssssssissesssssserisessesstesiestsstssseniesiesenntenieniesensnentes 3 4 3 3 1 Configuring Queuing Service Types s see ssesssesserissiessesiesiesiessessesisstestnsnententesnnnnententeneess 3 4 3 3 2 Configuring QUEUING Service cocicicnninnnnnnncnnnsannnnnnnononanananonononanananononan assa onononon anar iiri paesi sens 3 6 3 3 3 Configuring Administration siseses A i e a 3 7 3 3 3 1 Configuring Memory Management for a CommandReply Buffer 3 8 334 Configuring Monitorid8 mmocirnn iaa Sa aku Sk Ake Sep keevat eb AD 3 10 3 3 4 1 Configuring Reguest Reply Monitoring 3 11 3 3 4 2 Configuring Publish
49. arting from Launcher viril arta ia bp gh oise 4 1 4 2 Starting Manually from the Command LiN ocociciciconicinnnrananononananonanononononanononononononononononononononoconcnnns 4 2 4 3 Using Queuing Service as a Windows Service ccococicicinoninincononnonenconenononcnnnnnonananononananananonononananononanss 4 4 4 3 1 Enabling Queuing Service to Run as a Windows Servic rreeseerrseesserserssersseeesssessns 4 4 4 3 2 Running RTI Queuing Service as a Windows Service 4 4 4 3 3 Notes when Running as a Windows Service sirsrsenerenenetenveneneneeneneneneanenenenene 4 4 4 3 4 Stopping Queuing Service when it is Running as a Windows Service 4 5 4 3 5 Disabling Queuing Service from Running as a Windows Service 0 0 eens 4 5 Administering Queuing Service from a Remote Location 5 1 5 1 Enabling Remote Administrati0M ococioicinononoononnnnnnnconanananononanonononononononononononononononononon ono nonon on caninas 5 1 52 Remote Adminstration APL oorno aA EAEI AE dali JALULE E te A 5 1 5 21 Resource Identifier uti idolo barata ease 5 2 5 22 Sample Selector ii lis indie da lili iii dagas 5 3 5 3 Remote Administration TOpics sr sei reris caia io vedasid s si vee Aue at vea vee state 5 4 5 4 Remote Commands in Queuing Service imisneneterenenenenerenenerenererersnsnerenensnsnensnenensesnseeeees 5 5 54 1 Create SharedReaderQueue ccccccscssccss
50. ation of the persistent storage and configure the storage process If the persisted configuration is not found the service will be initialized using the input XML file When the service configuration is obtained remotely using the command line option cfgRe mote see Table 4 1 RTI Queuing Service Command Line Options any persisted configuration will be dropped and the service will always be initialized using the remote XML configuration The location and name of the file where the configuration is persisted is as follows directory prefix serviceO appName db Where I directory is configured using the tag lt directory gt under lt persistence_settings gt lt file system gt I prefix is configured using the tag file prefix gt under lt persistence_settings gt lt filesys tem gt I appName is configured using the command line parameter appName SharedReaderQueue Persistency A SharedReaderQueue can be configured to persist the undelivered samples into disk by setting the XML tag lt kind gt within lt shared_reader_queue gt lt queue_qos gt lt persistence gt to PERSIS TENT see Table 3 15 Queue QoS Tags Queuing Service provides two different PERSISTENT implementations 3 Without In Memory State In this mode the metadata and user data associated with the SharedReaderQueue s samples is kept only on disk Every time the metadata or user data is used Queuing Service reads it from disk O With In Memory
51. be successfully delivered and processed Queuing Service supports the definition of one dead letter queue per SharedSubscriber by using the XML tag lt dead_letter_shared_reader_queue gt The dead letter queue has two limitations compared with a regular queue 1 It cannot have a lt reply_type gt 2 It cannot have a lt type_name gt The type associated with the samples in a dead letter queue is DeadLetter_t defined as follows enum UndeliveredReasonKind LIFESPAN UNDELIVERED REASON KIND MAX RETRIES UNDELIVERED REASON KIND struct GUID t Dead Letter Queues octet value 16 struct SequenceNumber t long high unsigned long low struct SampleIdentity t GUID t writer guid SeguenceNumber t seguence number struct SampleBuffer t seguence lt octet gt value struct DeadLetter t string gueue name Sampleldentity t sample identity UndeliveredReasonKind undelivered reason SampleBuffer t sample buffer Extensibility EXTENSIBLE EXTENSIBILITY You can find the IDL file that defines the DeadLetter types in lt NDDSHOME gt resource id1 QueuingServiceTypes idl The queue_name has the format lt aQueueTopicName gt lt aSharedSubscriberName gt The sample_identity contains the identity of the undelivered sample The sample_buffer contains the sample data in serialized form with CDR representation To deserialize the sample data use the following operations LJ C FooTypeSupport_deserialize_dat
52. bscriber_1 gt lt shared reader queue name SharedReaderQueue_1 gt lt shared reader gueue gt lt shared subscriber gt lt domain participant gt lt gueuing service gt lt dds gt The resource identifier for the DomainParticipant is domain participant DomainParticipant 1 The resource identifier for SharedSubscriber is domain participant DomainParticipant 1 shared subscriber SharedSubscriber 1 The resource identifier for the SharedReaderQueue is domain_participant DomainParticipant_1 shared_subscriber SharedSubscriber_1 shared_reader_queue SharedReaderOueue 1 The resource identifier for the sample s in the SharedReaderOueue is domain participant DomainParticipant 1 shared subscriber SharedSubscriber 1 shared reader gueue SharedReaderOueue 1 message 5 2 Remote Administration API 5 2 2 The resource identifier for the SharedReaderOueue status is domain participant DomainParticipant 1 shared subscriber SharedSubscriber 1 shared reader gueue SharedReaderOueue 1 status Sample Selector For reguests that apply to messages in a SharedReaderOueue you may optionally provide a sample selector as part of the lt body gt The sample selector is an SOL like expression Expression Grammar Condition Predicate Condition AND Condition Condition OR Condition NOT Condition Condition Predicate ComparisonPredicate ComparisonPredicate ComparisonTerm RelOp Compar
53. cccccccccccccccccnncnnonnnnnnnn 9 1 9 1 Asymmetric TCP Communication With Queuing Service oconococooionononeonnnnononeonacinananonanacanananonono 9 1 9 2 Asymmetric TCP Communication with Queuing Service And Replication w 9 4 Chapter 1 Welcome to RTI Queuing Service RTI Queuing Service is a broker that provides a queuing communication model in which a sam ple is stored in a queue until it is consumed by one QueueConsumer If there are no QueueCon sumers available when the sample is sent the sample is kept in the queue until a QueueConsumer is available to process it If a QueueConsumer receives a sample and does not acknowledge it before a specified amount of time or acknowledges it negatively the sample will be redelivered to a different QueueConsumer Queuing Service provides an at most once and at least once delivery semantic By default Queuing Service keeps the samples in memory To provide fault tolerance Queuing Service can be configured to keep the samples on disk For high availability Queuing Service provides mechanisms to replicate its state so that samples can survive the loss of any particular service and or computer 1 1 Chapter 2 Queuing Service Architecture and Operation 2 1 Terms to Know You should become familiar with a few key terms and concepts L QueuingService instance A single application process service that is deployed and configured to host the gueues
54. ch other to repli cate SharedReaderOueues and or the service configuration Instances in different clusters are isolated form each other For SharedReaderOueue replication all instances within a cluster must have a lt domain_participant gt with the same lt domain_id gt see Configuring DomainParticipants Sec tion 3 3 6 For service configuration replication all instances within a cluster must use the same lt domain_id gt for remote administration See Configuring Administration Section 3 3 3 7 8 Replication Clusters Figure 7 4 Replication Cluster Cluster 1 Cluster 2 7 9 Chapter 8 Queuing Service Wrapper API 8 1 8 2 8 3 RTI Connext DDS provides a wrapper API to make it easier to interact with Queuing Service In this release the wrapper API is only supported in the NET API and is located in the namespace RTI Connext Queuing Important The wrapper API is only available with the Connext DDS Professional Evaluation and Basic package types it is not available with the Core package type QueueProducer Wrapper To simplify the use and configuration of a DataWriter to send samples to a SharedReaderQueue Connext DDS provides an abstraction QueueProducer lt aMessageType gt which wraps the DataWriter and provides additional services such as an operation to detect if there is a matching SharedReaderQueue or an operation to wait for application level acknowledgement after send ing a sample
55. cssssssesssessescsessssoesseesoessasseessenecsscessesssensecsscnsssassees 5 5 542 Delete SharedReaderQuelleninicnida tebe kokana E teke ku uk Sak i p as 5 6 543 Flush SharedReaderOueue cccccccccsssssessssscessessceccecseesseaecseceaecesssseeseseseseseseeeecseeseecaeceeeaes 5 6 5 4 4 Get SharedReaderOueue Status ccccccecssssssssesseescescecsecssessecsecesseseceeseseceseeseeeeseeeeeeseeeaecaes 5 6 DAD OEI Data ir iia ii ia exten t ihin nikkel be Pie Seto tees 5 7 5 4 6 Get Samples From a SharedReaderQueue oooocicionnononcnnonnnnincnnoronnncnnnononanonononon anno nnono ron cnnnananos 5 8 5 4 7 Create Shared Subscribe mii hen Skee ethos acs hades pe iv bcos 5 9 548 Delete Shared Subscribers iin ana shaka hie aiden je taak va ena ion te 5 9 5 5 Accessing Queuing Service from a Connext DDS applicati0M ococicicicononincnononancnnoninananonacananonononoso 5 9 Publish Subscribe Monitoring of Queuing Service from a Remote LOCOOM cai vssicsicsccciesscesccestnccscidecshesnsdasdtaceecsosoadensaissdvedesteddoasobernss 6 1 6 1 Enabling Publish Subscribe Monitoring Data ocociciininnnnonncaninoniccnnnanononononanonononononononononon oran onononcncnnns 6 1 62 Status Information for a Shared ReaderQueul c csccccessesssesseessesceseecsceseecsecssesaecssesaececeeeeeseeeeeesees 6 2 High AV abla ta 7 1 7 1 SharedReaderOueue ReplicatiON c conionnnonnnninncnnncnnnoncnnorononnnononoronnoninnnno ran cn crono non cn canina ronca nncnonananon
56. d where the value is set to the source GUID associated with the reguest For the example in Figure 2 6 the filter would be erelated source guid value hex lt SGUIDm gt Alternatively you can set the filter in the related reader guid as follows erelated reader guid value amp hex lt SGUIDm gt QueueRequester Wrapper To simplify the use and configuration of the DataReader and Data Writer in the requester applica tion Connext DDS provides an abstraction OueueReguester lt MessageReguestType Mes sageReplyType which wraps the DataReader and DataWriter usage and provide additional services such as an operation to wait for the response for a given request For more information see Chapter 8 Queuing Service Wrapper API In this release the QueueRequester wrapper API is only supported in the NET API QueueReplier Wrapper To simplify the use and configuration of the DataReader and DataWriter in the replier application Connext DDS provides an abstraction OueueReplier lt MessageReguestType MessageReply Type gt which wraps the DataReader and DataWriter usage For more information see Chapter 8 Queuing Service Wrapper API In this release the QueueReplier wrapper API is only supported in the NET API Dead Letter Queues Queuing Service provides support for dead letter queues A dead letter queue is a SharedReader Queue to which other SharedReaderQueues can send messages that for some reason could not
57. default remote publish subscribe monitoring is disabled in Queuing Service for security rea sons To enable remote monitoring you can use the lt monitoring gt tag see Configuring Publish Subscribe Monitoring Section 3 3 4 2 When remote publish subscribe monitoring is enabled Queuing Service creates L 1 DomainParticipant J 1 Publisher L 1 DataWriter to publish status data for SharedReaderQueues The QoS values for these entities are described in Configuring Publish Subscribe Monitoring Section 3 3 4 2 6 1 Status Information for a SharedRenderOueue 6 2 Status Information for a SharedReaderQueue The topic that publishes SharedReaderOueue status is called rti gueuing service monitoring shared reader gueue The registered type name for the topic is RTI OueuingService Monitoring SharedReader QueueStatus The type definition of the SharedReaderQueue status is called Shared ReaderQueueStatus and it can be found in the file lt NDDSHOME gt resource idl QueuingServiceTypes idl Queuing Service reports multiple statistics as part of the SharedReaderQueue status Some of these statistics are counters such as the number of samples received by a SharedReaderQueue and other statistics are statistics variables such as the number of samples enqueued per second in a SharedReaderQueue To see how statistics variable are calculated see Configuring Statistics Calculation Process Sec tion 3 3 4 3 6 2 Chapter 7 Hig
58. der Queue Return Value Upon success this command returns RTI SERVICE COMMAND REPLY OK in the retcode field of the reply The operational status is sent in serialized form within the octet_body field in the CommandReply If there is an error this command returns RTI SERVICE COMMAND REPLY ERROR and the field string body contains a human read able string describing the error Status Description The type of the SharedReaderQueue s status can be found in the file lt NDDSHOMEh gt resource idl QueuingServiceTypes idl To deserialize the status from the CommandReply octet_body use the following operations IJ C SharedReaderOueueStatusTypeSupport deserialize data from cdr buffer 5 6 Remote Commands in Oueuing Service 5 4 5 LJ C SharedReaderOueueStatusTypeSupport deserialize data from cdr buffer LI C CLI SharedReaderOueueStatusTypeSupport deserialize data from cdr buffer L C SharedReaderOueueStatusTypeSupport deserialize data from cdr buffer I Java SharedReaderOueueStatusTypeSupport get instance deserialize from cdr buffer When generating code for QueuingServiceTypes idl in C C and NET make sure you use the unboundedSupport command line option Get Service Data The following command is used to get the ServiceData that provides a sequence of SharedRead erQueueData This command provides a way to query all the SharedReaderQueues hosted in a service instance GET lt
59. des all the verbosity levels smaller than n version Prints the Queuing Service version number Using Queuing Service as a Windows Service 4 3 4 3 1 4 3 2 4 3 3 Using Queuing Service as a Windows Service Windows Services automatically run in the background when the system reboots Enabling Queuing Service to Run as a Windows Service If you want to run Queuing Service as a Windows Service you must install it as such before run ning it To install it as a Windows Service run the following command in a terminal with Administrator privileges lt NDDSHOME gt bin rtiqueuingservice installService By default Queuing Service is installed with the service name rtiqueuingservice520 If you want to install it with a different service name you can use the serviceName flag For instance you would enter this all on one line lt NDDSHOME gt bin rtiqueuingservice installService serviceName mycustomservicename Using the serviceName parameter with different names allows you to install multiple Queuing Service instances on the same host Running RTI Queuing Service as a Windows Service If you added Queuing Service as a Windows Service and want to run it without rebooting you can start it as a service from the command line with the Windows sc utility sc lt serviceName gt start By default it will start Queuing Service with the defaultService configuration that is stored in lt NDDSHOME gt
60. ducer gt false lt app ack sample to producer gt lt reliability gt Default app_ack_sample_to_producer true Oorl lt resource_limits gt This policy e Provides fine grained control over the resources memory and disk associated with the samples in a SharedReaderQueue e Provides a way to configure the behavior of a SharedReaderQueue when a new sample arrives and the SharedReaderQueue is full e Provides ways to monitor when the space taken by the samples in a Share dReaderQueue goes above or below configurable watermarks and when the SharedReaderQueue fills up For default values and additional information see SharedReaderQueue Resource Management Section 2 15 Oorl 3 25 XML Tags for Configuring Queuing Service Table 3 16 lt shared reader gueue gt Attributes Attributes for lt shared reader gueue gt Description Reguired dead letter gueue The name of the Dead Letter SharedReaderOueue associated with this SharedReaderOueue SeeDead Letter Oueues Section 2 12 No name The name of the SharedReaderOueue This name is needed to address the gueue using remote administration See Chapter 5 Administering Oueuing Service from a Remote Location If not specified the service generates a random name session The name of the session associated with the SharedReaderOueue See Configuring SharedSubscribers Sessions Section 3 3 9 for addi tio
61. e Oueuing Pattern OueueReguester QueueReplier Wrapper To simplify the use and configuration of the DataReader and DataWriter in the replier application Connext provides an abstraction QueueReplier lt MessageRequestType MessageReplyType gt which wraps the DataReader and DataWriter usage The Connext API Reference HTML documentation contains the full API documentation for the QueueProducer Under the Modules tab navigate to RTI Connext DDS API Reference RTI Connext Messaging API Reference Queuing Pattern QueueReplier 8 2 Chapter Communication Using TCP Transport 9 1 Oueuing Service and the applications that interact with it can be configured to communicate with each other using the TCP transport distributed with Connext DDS The transport can be configured via XML using the PropertyOosPolicy of the Oueuing Service s DomainParticipants and the applications DomainParticipants This chapter explains how to use and configure TCP communications with Queuing Service This chapter does not intend to provide an exhaustive explanation of the TCP transport and all of its configuration properties For details on the TCP transport see the RTI Connext DDS Core Librar ies and Utilities User s Manual The TCP transport distributed with Connext DDS can be used to address multiple communica tion scenarios that range from simple communication within a single LAN to complex commu nication scenarios across LANs where NATS and firew
62. e the reguester application will not be robust to potential restarts If the source GUID is different every time the reguester application restarts there may be responses that get lost since Oueuing Service will not know how to route them to the proper reguester application 2 11 2 Request Reply Correlation When the replier application receives a request sample from Queuing Service it must extract the source GUID and the sample identity in order to send them back as part of the reply to the requester application This allows requests and replies to be correlated The replier application can extract the identity of a request from the fields related_original_publication_virtual_guid and related_original_publication_virtual_sequence_number in the Samplelnfo associated with the request sample see Figure 2 6 Figure 2 6 Request Generation Requester Application Replier Application eee l take source guid SGUID_ related source guid SGUID identity writer guid GUID related original publication virtual guid GUID identity sequence_number SN related original publication virtual seguence number SN CFT Orelated_source_guid va DataWriter GUID DataReader GUID Queuing Service CET related_reader_guid value RS Request Queue __ Reply Queue UID gt Le SCO take write_w_params related_source_guid SGUID_ related_source_g
63. e from a Remote Location You can monitor Queuing Service remotely by subscribing to special topics By subscribing to these topics any Connext DDS application can receive information about the configuration and operational status of Queuing Service Being able to monitor the state of a Queuing Service instance is an important tool that allows you to detect problems For example looking at the enqueue throughput of a SharedReaderQueue you might see that the queue is receiving a lot of traffic and you may want to put that queue in its own session There are two kinds of monitoring data for en entity for example a SharedReaderQueue Entity data provides information about the configuration of the entity For example the service data contains a list of the SharedReaderQueues contained in the service Entity data information is updated every time there is a configuration change that affects that data L Entity status provides information about the operational status of an entity This kind of information changes continuously and is computed and published periodically For example the SharedReaderQueue status contains information such as the SharedReader Queue s latency and throughput Queuing Service only publishes entity status for SharedReaderQueues Entity data can be accessed using remote administration commands See Chapter 5 Administering Queuing Ser vice from a Remote Location Enabling Publish Subscribe Monitoring Data By
64. e will ensure that each sample is delivered to exactly one DataReader SharedReaderQueues exist within SharedSubscribers A SharedSubscriber has a name Shared SubscriberName that provides a scope for the shared ReaderQueue names Each SharedReader Queue is associated with exactly one DDS Topic A single SharedSubscriber is not allowed to host two SharedReaderQueues of the same Topic name hence the Topic name uniquely identifies the SharedReaderQueue within the SharedSubscriber For this reason the name of a shared ReaderQueue is defined by combining the two as in aTopicName aSharedSubscriberName DataWriter Connection to a SharedReaderQueue You can use a Data Writer to send data to a SharedReaderQueue The DataWriter simply writes to the Topic that is associated with a SharedReaderQueue With regards to QoS the DataWriter can specify any DataWriter QoS except reliability kind must be set to RELIABLE_RELIABILITY_QOS and reliability acknowledgment kind must be set to APPLICATION EXPLICIT ACKNOWLEDGMENT MODE The DataWriter is typically also configured with durability kind set to VOLATILE DURABILITY OOS 2 4 DataReader Connection to a Shared ReaderOueue 2 4 1 2 4 2 2 5 For every received sample Queuing Service sends an application level acknowledgement AppAck message to the QueueProducer s DataWriter indicating successful processing or rejec tion the sample The sending of the application level acknowledgeme
65. eSupport get instance deserialize from cdr buffer 5 8 Accessing Oueuing Service from a Connext DDS application 5 4 7 5 4 8 5 5 When generating code for QueuingServiceTypes idl in C C and NET make sure you use the unboundedSupport command line option Create SharedSubscriber The following command is used to create a SharedSubscriber CREATE lt target gueuing service gt lt domain participant resource identifier gt lt xml url gt Parameters Lj lt domain_participant_resource_identifier gt is the resource identifier for the DomainPartici pant that will contain the SharedSubscriber L lt xml_url gt contains an XML snippet containing the SharedSubscriber configuration A full file starting with lt dds gt is not valid For example str lt shared_subscriber name SharedSubscriber_1 gt lt shared_subscriber gt Return Value Upon success this command returns RTI SERVICE COMMAND REPLY OK in the retcode field of the reply Otherwise this command returns one of the following values and the field string_body contains a human readable string describing the error LL RTL SERVICE COMMAND REPLY ALREADY EXISTS if the SharedSubscriber already exists with a different configuration L RTL SERVICE COMMAND REPLY DUPLICATED if the SharedSubscriber already exists with the same configuration 3 RTI SERVICE COMMAND REPLY ERROR for any other creation error Delete SharedSubscriber
66. eallocates the samples in the QueueProducer s DataWriter queue and the keys stored with the instances to their maximum size If the SharedReaderQueue type has variable size members sequences and or strings with large maximum size this may lead to high memory usage For information on how to reduce memory consumption on a DataWriter see Sample Data and Instance Data Memory Management in the RTI Connext DDS Core Libraries User s Manual DataReader Connection to a SharedReaderQueue You can use a DataReader to read samples from a SharedReaderQueue as long as the DataReader is configured as follows LJ The DataReader must attach to the SharedSubscriber that contains the SharedReader Queue It does this by setting the property dds data_reader shared_subscriber_name in reader_qos property with a value that is equal to the SharedSubscriberName This prop erty must be propagated as follows lt element gt lt name gt dds data_reader shared_subscriber_name lt name gt lt value gt MySharedSubscriberName lt value gt lt propagate gt true lt propagate gt lt element gt 2 5 Queuing Service Entities 2 5 1 2 5 2 2 6 d The DataReader must set a ContentFilteredTopic on the related_reader_guid Queuing Service uses this filter to distribute a sample only to the DataReader that has been selected for the sample see Sample Distribution to a Selected QueueConsumer Section 2 7 LJ The DataReader must subscribe to the Top
67. ecifies the maximum amount of time in seconds that Queuing Service will wait for an initial configuration when using cfgRemote Default 20 seconds daemon Runs Queuing Service as a daemon Windows service When this flag is present Queuing Service will start in the background Note that some sys tems may require special privileges to do this domainldBase lt ID gt Sets the base domain ID This value is added to the domain IDs in the configuration file For exam ple if you set domainIdBase to 50 and use domainIDs 0 and 1 in the con figuration file then Oueuing Service will use domains 50 and 51 Default 0 help Displays help information 4 2 Starting Manually from the Command Line Table 4 1 RTI Queuing Service Command Line Options Option Description remoteAdministrationDomainld Enables remote administration and sets the domain ID for remote commu nication When remote administration is enabled Oueuing Service will create a DomainParticipant Publisher Subscriber DataWriter and DataReader in the designated domain See Chapter 5 Administering Oueuing Service from a Remote Location in lt ID gt the Queuing Service User s Manual This option overrides the value of the tag lt domain_id gt within a lt admin istration gt tag This parameter is required when using cfgRemote Default Remote administration is not enabled unless it is enabled from the XM
68. equence number 1 original sample identity writer guid value amp hex 00000000000000000000000000000001 AND original sample identity sequence number 0 1 Remote Administration Topics For remote administration Queuing Service creates two topics I rti service admin command_request is used to send a command from a client to Queu ing Service I rti service admin command reply is used to send the command response s from Queu ing Service to the client The topics have these corresponding types I RTI Service Admin CommandReguest 5 4 Remote Commands in Oueuing Service LI RTI Service Admin CommandReply You can find the IDL definitions for these types in lt NDDSHOME gt resource idl ServiceAd min idl struct CommandRequest EntityName service name ServiceKind service CommandActionKind action Resourceldentifier resource identifier StringBody string body OctetBody octet body CExtensibility EXTENSIBLE EXTENSIBILITY struct CommandReply CommandReplyRetcode retcode long native_retcode StringBody string body OctetBody octet_body etop level true Extensibility EXTENSIBLE EXTENSIBILITY The field native_retcode in the CommandReply is reserved for future use When generating code for ServiceAdmin idl in C C and NET make sure to use the com mand line option unboundedSupport 5 4 Remote Commands in Queuing Service This section describes the remote commands avail
69. er in Oueuing Service Section 3 5 0or1 lt domain id gt Specifies which domain ID Queuing Service will use to enable remote administration 1 required lt memory_management gt Controls how Queuing Service allocates memory for the string_body or octet_body buffer in a CommandReply See Configuring Memory Management for a CommandReply Buffer Section 3 3 3 1 0or1 lt participant_qos gt Configures the DomainParticipant QoS for remote administration If the tag is not defined Queuing Service will use the Connext DDS defaults 0or1 lt publisher_qos gt Configures the Publisher QoS for remote administration If the tag is not defined Queuing Service will use the Connext DDS defaults Dor1 lt subscriber_qos gt Configures the Subscriber QoS for remote administration If the tag is not defined Queuing Service will use the Connext DDS defaults Dor1 L sample buffer min size If the size required for the buffer of a CommandReply is smaller or equal to this value Queuing Service will use a pre allocated buffer The size of this buffer is equal to this value If the size required for the buffer of a CommandReply is greater than this value Queuing Service will allocate the buffer from the heap dynamically upon reply generation L sample buffer trim to size This value controls what to do with the CommandReply buffer that is dynamically allocated When true the buffer w
70. erQueue syn chronization information between Queuing Service instances To configure QoS of this DomainParticipant use the lt domain participant gt lt participant gos gt tag see Configur ing DomainParticipants Section 3 3 6 2 The second DomainParticipants is used to receive remote administration commands To configure its QoS use the lt administration gt lt participant gos gt tag see Configuring Administration Section 3 3 3 Asymmetric TCP Communication with Oueuing Service And Replication When Queuing Service is configured to replicate configuration it creates one more DomainPartic ipants to replicate the configuration The OoS of this DomainParticipants is configured using lt configuration replication gt lt participant gos gt see SharedReaderOueue for Configuration Replication Section 7 2 1 All this DomainParticipants must be configured to use TCP This TCP communication scenario will require creating two instances of the TCP transport in each one of the DomainParticipants created by the Queuing Service QS instances I The first instance runs in asymmetric mode and is used to allow the Queuing Services to communicate with Producers Consumers and Remote Administration applications LJ The second instance runs in symmetric mode and is used for communication between Queuing Services Symmetric mode means that each service will create a server socket that other services will use to establish connections T
71. field consumer_id must be used to identify the QueueConsumer that sends the Availability sample This field must be the same value that was used to set the QueueConsumer ContentFil teredTopic described in Sample Distribution to a Selected QueueConsumer Section 2 7 By default when using ROUND_ROBIN policy a SharedReaderQueue does not create a DataReader to receive availability updates from a QueueConsumer To enable that behavior set the property ALLOW_CONSUMER_FEEDBACK to 1 For example lt distribution gt lt kind gt ROUND_ROBIN lt kind gt lt property gt lt value gt lt element gt lt name gt UNACKED THRESHOLD lt name gt lt value gt 1 lt value gt Sending a Reply from QueueConsumer to QueueProducer lt element gt lt element gt lt name gt ALLOW CONSUMER FEEDBACK lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt lt distribution gt Notice that in a SharedReaderQueue with the previous configuration it is possible to have some QueueConsumers reporting availability through the new topic and some QueueConsumers not reporting availability and using the configuration threshold under lt distribution gt 2 11 Sending a Reply from QueueConsumer to QueueProducer Queuing Service also supports a request reply communication model in which a requester appli cation sends a sample to a SharedReaderQueue and a replier application receives the sample from the SharedReaderQ
72. figuring Queuing Service Table 3 14 SharedReaderAueue Tags Tags within lt shared reader gueue gt Description Number of Tags Allowed lt reply topic gt The topic name for the implicit Reply SharedReaderOueue created by setting lt reply_type gt This tag is ignored if lt reply_type gt is not set Default lt topic_name gt Reply 0or1 lt reply type gt The name of the type associated with a Reply SharedReaderQueue When it comes to the creation of a Reply SharedReaderQueue you have two options e Declare the queue explicitly in the configuration file e Declare the queue implicitly through the usage of lt reply_type gt In this case the configuration of the Reply SharedReaderQueue matches the configuration of the Share dReaderQueue containing lt reply_type gt See Sending a Reply from QueueConsumer to QueueProducer Sec tion 2 11 0or1 lt topic name gt The name of the Topic associated with the SharedReaderQueue QueueProducers will publish on this Topic QueueConsumers will subscribe to a Topic with name lt topic_name gt SharedSubscriber Name where SharedSubscriberName is the name of the Shared Subscriber containing the SharedReaderQueue See Queuing Service Entities Section 2 6 1 required lt type_name gt The name of the type associated with the ShareReaderQueue See Configuring Queuing Service Types Section 3 3 1 1 required
73. g Service will also receive the data sent by the QueueProducer Figure 2 4 Queuing Service Endpoint Matching with non QueueConsumer DataReaders Queuing Service Shared Subscriber rtiddspy Producer Order DR Order NY_EX DR Order DW Order NY_EX Order NY_EX z Consumer Order NY_EX lt Consumer Order NY EX rtiddspy DR Order DW DataWriter DR DataReader 2 9 Sample Lifecycle In Queuing Service The samples received by a Queuing Service instance have a lifecycle described by the following states L Engueued The sample has been received by Queuing Service and has been stored in the SharedReaderQueue persistent or in memory In addition if SharedReaderQueue replication is enabled the sample must have been received and stored by a quorum of up to date replicas See Chapter 7 High Availability I Assigned The sample has been assigned to one of the QueueConsumers In addition if SharedReaderQueue replication is enabled the selected QueueConsumer must have been communicated to the replicas and optionally confirmed by a quorum of up to date replicas See Chapter 7 High Availability IJ Sent The sample has been sent to the designated QueueConsumer L Delivered The sample has been delivered to a QueueConsumer and the application level acknowledgment of the successful deli
74. h Availability 7 1 Figure 7 1 For high availability Queuing Service can be configured to replicate both the content of the SharedReaderQueues and the service configuration SharedReaderQueue Replication By default SharedReaderQueues within a Queuing Service instance are not replicated Share dReaderQueues can optionally be replicated across multiple instances of Queuing Service run ning in the same or different nodes See Figure 7 1 Replicating SharedReaderQueues Queuing Service 1 Queuing Service 2 i i queuel i gueue 1 queue 1 gueue 3 Queuing Service 3 J SharedReaderQueue Replication Protocol Each replicated SharedReaderQueue consists of one master and multiple slaves Only the mas ter SharedReaderQueue distributes messages to the QueueConsumers DataReaders When the master goes away the most up to date slave is promoted into master 7 1 SharedReaderQueue Replication The replication protocol has four different phases 1 2 3 4 Sample replication Enqueue Consumer assignment Delivery 7 1 1 1 Sample Replication Phase During this phase the samples published by a QueueProducer s Data Writer are distributed to all replicas master and slaves There are two ways to do this 1 The QueueProducer s DataWriter sends directly the samples to all the replicas This is the preferred way to distribute the sample as it provides the best performance es
75. he following XML snippet shows how to configure the TCP transport in Queuing Service lt gos library name TCPLibrary gt lt gos profile name TCPProfile gt lt participant goSs gt lt property gt lt value gt lt element gt lt name gt dds transport load plugins lt name gt lt value gt dds transport tcp dds transport tcp2 lt value gt lt element gt lt element gt lt name gt dds transport tcp library lt name gt lt value gt nddstransporttcp lt value gt lt element gt lt element gt lt name gt dds transport tcp parent classid lt name gt lt value gt NDDS TRANSPORT CLASSID TCPV4 WAN lt value gt lt element gt lt element gt lt name gt dds transport tcp create function lt name gt lt value gt NDDS Transport TCPv4 create lt value gt lt element gt lt element gt lt name gt dds transport tcp2 library lt name gt lt value gt nddstransporttcp lt value gt lt element gt lt element gt lt name gt dds transport tcp2 parent classid lt name gt lt value gt NDDS TRANSPORT CLASSID TCPV4 LAN lt value gt lt element gt lt element gt lt name gt dds transport tcp2 create function lt name gt lt value gt NDDS Transport TCPv4 create lt value gt lt element gt lt value gt lt property gt lt participant_qos gt lt qos_profile gt lt gos library gt lt gueuing Service name Service gt lt administration gt lt domain id gt 1 lt domain id gt lt participant gos base name TC
76. ic lt SharedReaderQueue Topic Name gt lt SharedSubscriberName gt With regards to QoS the DataReader can specify any DataReader QoS except reliability kind must be set to RELIABLE_RELIABILITY_QOS and reliability acknowledgment_kind must be set to APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE The DataReader is typically also configured with durability kind set to VOLATILE_DURABILITY_QOS The application must acknowledge the successful processing or rejection of a received sample using the DataReader s acknowledge sample and or acknowledge_all operations The response data for successfully processed samples will be a single byte set to 1 The response data for rejected samples will be a single byte set to 0 For more information on the sample lifecycle in a SharedReaderQueue see Sample Lifecycle In Queuing Service Section 2 9 QueueConsumer Wrapper To simplify the use and configuration of a DataReader to receive samples from a SharedReader Queue Connext DDS provides an abstraction QueueConsumer lt MessageType gt which wraps the DataReader and provide additional services such as an operation to detect if there is a match ing SharedReaderQueue or a blocking operation to receive samples For more information see Chapter 8 Queuing Service Wrapper API Note In this release the QueueConsumer wrapper API is only supported in the NET API Samples with Large Maximum Size By default Connext DDS preallocates the samples i
77. ication settings gt under lt gueuing service gt The replication protocol is configured using the lt replication settings gt tag see Table 7 3 Repli cation Settings Tags 7 5 SharedReaderOueue Replication 7 1 3 1 Table 7 3 Protocol Information Exchange The replication of SharedReaderQueues requires the exchange of status information among rep licas This is done by creating a DataWriter and a DataReader per SharedReaderQueue to publish and subscribe to this information The QoS for these entities can be configured using the tags lt update datawriter gos gt and lt update datareader gos gt under the lt shared_reader_queue gt tag see Table 3 14 SharedRead erQueue Tags Replication Settings Tags Tags within lt replication_settings gt Description Number of Tags Allowed lt queue_instances gt The number of expected replicas including the master for a SharedReaderQueue Default 2 0or1 lt master timeout gt A new master election process will be initiated if the master does not send messages to the replicas before this timeout expires Example lt master timeout gt lt sec gt 5 lt sec gt lt nanosec gt 0 lt nanosec gt lt master timeout gt Default 5 seconds 0or1 lt synchronize consumer assignment gt Indicates if the master must wait for the slaves to receive the OueueConsumer assignment before sending a sample to the selected QueueCo
78. ill be released when the cor responding reply is sent When false the buffer is retained for future responses It may be released later on but only to be replaced by a larger buffer Ranges L sample buffer min size 1 2 GB the maximum size of a CommandReply or a positive number I sample buffer trim to size true or false Defaults L sample buffer min size 32768 LJ sample buffer trim to size false 3 9 XML Tags for Configuring Queuing Service 3 3 4 Configuring Monitoring With Queuing Service you can monitor the status of the service and its SharedReaderQueues using request reply or publish subscribe communication patterns Request reply monitoring is done by issuing remote administration commands that retrieve the status of the different entities in the service See Chapter 5 Administering Queuing Service from a Remote Location publish subscribe monitoring is done by subscribing to the monitoring topics See Chapter 6 Publish Subscribe Monitoring of Queuing Service from a Remote Location To enable Request Reply monitoring and configure its behavior use the lt administration gt tag under lt queuing_service gt See Configuring Administration Section 3 3 3 To enable Pub Sub monitoring and configure its behavior use the lt monitoring gt tag under lt queuing_service gt See Configuring Publish Subscribe Monitoring Section 3 3 4 2 By default both remote publish subscribe monit
79. ion 3 3 3 or the remoteAdministrationDomainId lt ID gt command line parameter which enables remote administration and sets the domain ID for remote communica tion For more information about the command line options see Queuing Service runs as a sep arate application The script to run the executable is in lt NDDSHOME gt bin There are four ways to start Queuing Service Section When remote administration is enabled Queuing Service will create a DomainParticipant Pub lisher Subscriber DataWriter and DataReader in the designated domain The QoS values for these entities are described in Configuring Administration Section 3 3 3 Remote Administration API Queuing Service provides a RESTful style remote administration API in which the commands have the following format lt ACTION gt lt target_queuing_service gt lt resource_identifier gt lt body gt Where 1 lt ACTION gt is one the following values CREATE DELETE GET Lj lt target_queuing_service gt can be e The application name of a Queuing Service instance such as MyOueuingService1 as specified at start up with the command line option appName see Table 4 1 RTI Queuing Service Command Line Options e A regular expression as defined by the POSIX fnmatch API 1003 2 1992 section B 6 for a Queuing Service application name such as MyQueuingService 5 1 Remote Administration API IJ lt resource identifier gt identifies the re
80. is field contains the lt status_publication_period gt For the up time metrics this field contains the time since the entity was created For the other windows this field contains a fixed value that identifies the window size 5000 for the 5 second window 60000 for the one minute window etc Statistics Calculation The accuracy of the statistics calculation process is determined by the value of the statistics sam pling period This period specifies how often statistics are gathered and is configured on a per entity basis using the tag lt statistics_sampling_period gt under lt statistics gt As a general rule the statistics sampling period of an entity must be smaller than its status_publication_period for publish subscribe monitoring and the request period for request reply monitoring A small statistics sampling period provides more accurate statistics at expense of increasing the memory consumption and decreasing performance The statistics calculation process is configured using the tags lt statistics gt under lt gueuing service gt and lt shared reader gueue gt Configuring Persistence Settings The lt persistence_settings gt tag configures the store settings that are used to persist the service state and the SharedReaderOueues s states see Queuing Service Persistency Section 2 14 Table 3 8 Persistence Setting Tags lists the tags that you can specify in lt persistence_settings gt Configuring DomainParticipant
81. is flag is not set Samples Each one of the samples returned by this command in the field octet body of the reply is encap sulated in a Message type which has the following definition struct Message MessageStatusKind status Sampleldentity t original virtual sample identity CDR serialized content of the SharedReaderQueue sample SampleBuffer t sample buffer Extensibility EXTENSIBLE EXTENSIBILITY The type can be found in the file lt NDDSHOME gt resource idl QueuingServiceTypes idl To deserialize the Message from the CommandReply octet_body use the following operations LJ C MessageTypeSupport_deserialize_data_from_cdr_buffer LJ C MessageTypeSupport deserialize data from cdr buffer LJ C CLI MessageTypeSupport deserialize data from cdr buffer LJ C MessageTypeSupport deserialize data from cdr buffer I Java MessageTypeSupport get instance deserialize from cdr buffer The sample buffer field in Message contains the serialized SharedReaderOueue s sample To deserialize the sample use the following operations where lt Foo gt is the type of the SharedRead erQueue s samples LJ C lt Foo gt TypeSupport deserialize data from cdr buffer L C lt Foo gt TypeSupport deserialize data from cdr buffer LJ C CLI lt Foo gt TypeSupport deserialize data from cdr buffer LJ C lt Foo gt TypeSupport deserialize data from cdr buffer I Java lt Foo gt Typ
82. isonTerm ComparisonTerm FieldIdentifier Parameter FieldIdentifier FIELDNAME RelOp lt gt Parameter SEQUENCE NUMBER INTEGER_VALUE BOOLEAN VALUE STRING OCTET ARRAY Token Expressions L FIELDNAME A reference to a field in the data structure A period is used to navigate through nested structures The number of dots that may be used in a FIELDNAME is unlimited An symbol prepending the field indicates that the field is a metadata field L INTEGERVALUE Any series of digits optionally preceded by a plus or minus sign representing a decimal integer value within the range of the system L or T must be used for long long otherwise long is assumed A hexadecimal number is preceded by 0x and must be a valid hexadecimal expression L BOOLEANVALUE Can either be TRUE or FALSE and is case insensitive J STRING Any series of characters encapsulated in single quotes except the single quote itself L OCTET_ARRAY An array of octets represented as follows amp hex hex_octet_values For example zhex 0708090A0B0C0D0E0F10111213141516 Here the left most pair represents the byte and index 0 L SEQUENCE_NUMBER A sequence number represented by a pair high low For example 2 3 5 3 Remote Administration Topics 5 3 Supported Field Names The only field names supported in this release are LJ Ooriginal sample identity writer guid value L Ooriginal sample ident
83. ity seguence number L Osample gueue status The original sample identity identifies a sample sent by the OueueProducer The identity con sists of a pair Virtual Writer GUID Virtual Sequence Number By default the identity of a sample published with a QueueProducer s DataWriter is automati cally set by the middleware You can access this value by using the write w params operation It is also possible to explicitly set the sample identity by using the same write_w_params oper ation For details on how to set and retrieve the sample identity see Section 6 3 8 Writing Data in the RTI Connext DDS Core Libraries User s Manual The sample_queue_status is a mask that represents the status of a sample in a SharedReader Oueue The possible statuses are L UNDELIVERED MESSAGE STATUS L SENT MESSAGE STATUS J DELIVERED MESSAGE STATUS Sample Selector Examples To select all the samples that have been sent to a QueueConsumer but not acknowledged yet Osample gueue status SENT MESSAGE STATUS To select all the samples that have been not been delivered to a OueueConsumer yet sample_queue_status SENT MESSAGE STATUS UNDELIVERED MESSAGE STATUS To select all the samples coming from a QueueProducer s DataWriter identified by virtual GUID 1 original sample identity writer guid value amp hex 00000000000000000000000000000001 To select the sample coming from a QueueProducer s DataWriter identified by virtual GUID 1 with s
84. match the QueueProducer lt aMessageType gt LJ The Queuing Service DataWriter will only match the QueueConsumer lt aMessageType gt Figure 2 2 Queuing Service Entities and Topics Fa gt Queuing Service Shared Subscriber Producer Order DR Order DW Order NY_EX A Consumer Order NY_EX 4 Consumer Order NY_EX aTopicName Topic with name aTopicName 2 7 Sample Distribution to a Selected AueueConsumer Queuing Service implements the logic that decides which QueueConsumer DataReader gets each sample To distribute a sample to the selected QueueConsumer the QueueConsumer DataReader uses a ContentFilteredTopic on the related_reader_guid For example orelated reader guid value amp hex 00000000000000000000000000000007 2 7 Interaction of Publish Subscribe Entities with Oueuing Service Entities Queuing Service uses the write w param operation on the SharedReaderOueue DataWriter to set the related reader guid to the value specified in the filter expression of the selected DataReader see Figure 2 3 Figure 2 3 Sample Distribution to Selected AueueConsumer DataReader 2 8 DR Topic Order NY_EX CFT Orelated_reader_guid value amp hex 000000000000000000000000000000FF DW Order NY_EX DR Topic Order NY_EX CFT related_reader_guid value am
85. mental count gt lt gueue allocation settings gt lt resource_limits gt In the above example LI initial count Queuing Service will pre allocate ten queue samples in advance 9 max count The maximum number of samples that the queue can hold is UNLIMITED 3 incremental count As additional samples are needed Oueuing Service will double the amount of extra memory allocated each time memory is needed Ranges initial count positive number and lt max count L max count LENGTH UNLIMITED or positive number M incremental count 1 double or positive number Defaults LJ initial count 1 J max count LENGTH UNLIMITED 3 incremental count 1 When max count is exceeded the behavior of a SharedReaderOueue when new samples are received can be configured using lt replacement policy gt under lt resource limits gt See Sample Replacement Policy Section 2 15 4 Maximum Number of Bytes in Memory The tag lt resource limits gt under lt shared reader gueue gt lt gueue gos gt can also be used to configure the maximum size of a SharedReaderOueue based on the number of bytes reguired to store the samples in memory For example lt resource limits gt lt gueue allocation settings gt lt max in memory bytes gt 1000000 lt max in memory bytes gt lt gueue allocation settings gt lt resource_limits gt In the above example the size required to store the SharedReaderQueue samples in memory cannot exceed 1 000 0
86. mple will be rejected if there is no space for it in the SharedReaderOueue When a sample is rejected and if lt app ack sample to producer gt is set to true for the SharedReaderOueue Queuing Service will send an AppAck message to the OueueProducer with a payload byte set to 0 This version of Oueuing Service supports two kinds of replacement policies LJ REJECT WITHOUT REPLACEMENT New samples are rejected when the SharedRead erQueue is full 2 23 High Availability 2 16 2 17 J WAIT WITHOUT REPLACEMENT New samples are kept in the SharedReaderQueue s DataReader cache until they can be added to the SharedReaderOueue Default LJ kind REJECT WITHOUT REPLACEMENT Notice that the WAIT WITHOUT REPLACEMENT replacement kind allows you to implement a flow control mechanism with the OueueProducer s DataWriter in which the DataWriter s write operation will block if new samples cannot be added to the SharedReaderOueue To achieve this behavior J The SharedReaderQueue s DataReader s cache must have a finite size This can be done by configuring lt shared reader gueue gt lt datareader gos gt lt resource limits gt lt max samples gt to a finite number J The OueueProducer s DataWriter s send window size must be a finite value This can be done by configuring lt datawriter gos gt lt protocol gt lt rtps reliable writer gt lt max send window size gt If a new sample arrives to the SharedReaderOueue
87. n you must use the lt configuration replication gt tag under lt service gos gt When this occurs Oueuing Service creates a special SharedReaderOueue that is used to replicate the remote administration commands across all the instances in the replication 7 7 Replication Clusters cluster This SharedReaderOueue is replicated and the replication settings are configured using the lt replication settings gt flag under lt configuration replication gt Table 7 4 Configuration Replication Tags describes the tags allowed within a lt configuration replication gt tag Table 7 4 Configuration Replication Tags 7 3 sil Number Tags within Descrivti fT lt configuration_replication gt escfiption a BS Allowed Enables disables configuration replication lt enabled gt 0or1 Default true Configures the DomainParticipant QoS for configuration A replication This DomainPartipant runs on the administra lt participant_qos gt 0 or1 tion domain ID If the tag is not defined Queuing Service will use the Connext DDS defaults Configures the configuration replication protocol See Table 7 3 Replication Settings Tags lt replication_settings gt Default If not set the replication settings are inherited 0 or 1 from the settings in lt replication_settings gt under lt queuing_service gt Replication Clusters A replication cluster is a set of Queuing Service instances that coordinate with ea
88. n be considered not engueued At this point it is responsibility of the application to decide whether or not to republish the sample Consumer Assignment Phase During the consumer assignment phase the master selects a QueueConsumer as the destination for a message according to the distribution policy configured for the SharedReaderQueue see Selecting a QueueConsumer for a Sample Section 2 10 After the QueueConsumer has been selected the master notifies all the slaves about this selec tion Then there are two possibilities The master sends the sample to the QueueConsumer immediately 2 The master waits until it gets confirmation from the quorum of most up to date slaves indicating that they received the assignment before it sends the sample to the Queue Consumer This behavior con be configured using the XML tag lt synchronize_consumer_assignment gt under lt replication_settings gt see SharedReaderOueue Replication Configuration Section 7 1 3 If the master goes away the slave promoted to master will try first to send the samples to the assigned QueueConsumer if this QueueConsumer is still in the system These samples will be marked with the DDS_REDELIVERED_SAMPLE flag Delivery Phase After a QueueConsumer sends an application level acknowledgment to the master indicating that a sample has been processed successfully the master notifies all the slaves about this deci sion and it removes the sample from the SharedReade
89. n the QueueConsumer s DataReader queue and the keys stored with the instances to their maximum size If the SharedReaderQueue type has variable size members sequences and or strings with large maximum size this may lead to high memory usage For information on how to reduce memory consumption on a DataReader see Sample Data and Instance Data Memory Management in the RTI Connext DDS Core Libraries User s Manual Queuing Service Entities A SharedReaderQueue is the result of the association of a Topic with a SharedSubscriber For each SharedReaderQueue Queuing Service instantiates L A DataReader to receive data from the QueueProducer lt aMessageType gt LJ A DataWriter to send data to the QueueConsumer lt aMessageType gt In the entities above aMessageType refers to the data type of the Topic associated with the Shared ReaderQueue The Queuing Service DataReader subscribes directly to the SharedReaderQueue Topic with name aTopicName Thus the Queuing Service DataReader which will match the QueuePro ducer lt aMessageType gt DataWriter subject to normal DDS type and QoS matching 2 6 Sample Distribution to a Selected OueueConsumer The Queuing Service DataWriter publishes a Topic whose name is obtained by concatenating the SharedReaderOueue Topic name aTopicName with the SharedSubscriber name aSharedSub scriberName as in aTopicName aSharedSubscriberName With this Topic name I The Queuing Service DataReader will only
90. nal information on sessions Yes 3 3 11 Configuring DeadLetterSharedReaderQueues Queuing Service provides support for deal letter queues A deal letter queue is a SharedReader Queue to which other SharedReaderQueues can send messages that for some reason could not be successfully delivered and processed Queuing Service supports the definition of one deal letter queue per SharedSubscriber by using the XML tag lt dead_letter_shared_reader_queue gt The deal letter queue has two limitations compared with a regular queue I It cannot have a lt reply_type gt I It cannot have a type names By default SharedReaderQueues do not send undelivered samples to the deal letter queue To enable this behavior you must use the attribute dead_letter_queue in lt shared_reader_queue gt This attribute must be set to the name of the deal letter queue in the configuration file For more information see Dead Letter Queues Section 2 12 3 26 Using Variables in XML 3 4 Using Variables in XML The text within an XML tag can refer to a variable To do so use the following notation MY VARIABLE For example lt element gt lt name gt The name is MY NAME lt name gt lt value gt The value is MY VALUE lt value gt lt element gt When the XML parser parses the above tags it will replace the references to variables with their actual values as follows 1 First it will try to get the variable val
91. name gt Assigns a name to the execution of Queuing Service Remote commands will refer to the queuing service using this name In addition the name of DomainParticipants created by Queuing Service will be based on this name Default The name given with cfgName if present otherwise it is RTI_Queuing_ Service cfgFile lt name gt Specifies a configuration file to be loaded This parameter is required See Section 3 1 How to Load the XML Configuration in the Queuing Ser vice User s Manual cfgName lt name gt Specifies a configuration name Queuing Service will look for a matching lt queuing_service gt tag in the configuration file This parameter is required unless cfgRemote is used cfgRemote Specifies that the initial configuration of the service must be obtained remotely from other running instances Using this option also requires the use of remoteAdministrationDo mainld to enable remote administration because the initial configuration will be received in the remote administration domain ID If you use this option and cfgName the service will wait until a configu ration with that name is received Otherwise the service will use the first configuration that it receives If the service does not receive the initial configuration after a configurable timeout see cfgRemoteTimeout it will load the configuration from the input configuration file s cfgRemoteTimeout lt n gt Sp
92. nd on disk only when 00r1 3 24 XML Tags for Configuring Queuing Service Table 3 15 Queue QoS Tags Tags within lt queue_qos gt Description Number of Tags Allowed lt redelivery gt Configures the redelivery policy for the SharedReaderQueue Example lt redelivery gt lt max delivery retries gt 10 lt max delivery retries gt lt response timeout gt lt duration gt lt sec gt 60 lt sec gt lt nanosec gt 0 lt nanosec gt lt duration gt lt response_timeout gt lt redelivery gt In the above example e lt max delivery retries gt configures the maximum number of redelivery attempts for a sample in a SharedReaderOueue e lt response_timeout gt configures the maximum time that Queue Service waits for an acknowledgment from the QueueConsumer to which the sample was sent to After that timeout expires the sample is redelivered to a different QueueConsumer for lt max_delivery_retries gt Defaults e Formax delivery retries 0 e For response_timeout UNLIMITED Oorl lt reliability gt Configures the QoS for reliable delivery of samples from a QueueProducer to the Queuing Service This release supports only one configuration parameter which allows you to dis able the sending of application level acknowledgement messages from Queuing Ser vice to the QueueProducers after samples are stored into a SharedReaderQueue Example lt reliability gt lt app ack sample to pro
93. nenenenenenenenenenene 2 13 2 11 11 Requester Identifications nei pa aa 2 13 2 112 Request Reply Correlation siminya tana 2 14 2 11 3 Sending the Reply Sample to the Associated Requester mimmenensenenenenete 2 15 2 11 4 QuevieRequester Wrappers sisesma aes eh NEE iit i a AT E E a isis 2 15 2 11 5 QueueReplier Wrappet ispis hiies n aa 2 15 2 12 Dead Letter Duele ina A ete a er S adilar anie aei a 2 15 2 13 Detecting the Presence of a SharedReaderQueue eoococoncnonoononnennncanannnnncnnnnnnnncanananonnnnnrarannarananannanos 2 17 2 14 Queuing Service PErSISTEMEY suuosa aa a a a ai ea 2 17 2141 Service State Persistency acca acca ag GG GH suriasesi to eei E EE E E EEE E E tito iE 2 17 2 14 2 SharedReaderQueue Persistency 0ssisienseesenesesesesenenesesesenenesesesesenesesnseseneneess 2 18 2 14 2 1 The Restore PrOCeSS 144 41 fic iia ia 2 20 2 15 SharedReaderQueue Resource Management ocencocononenennnncannnnnnnnnrannnnenanananonnnnarnnannnnnnanarnrnararananannnnos 2 20 2 15 1 Maximum SharedReaderOueue Size ccccccccsscssecssessecsscesecsecsssseseeseseeeeceseeeeecseesaecssceeeaees 2 20 iii 2 15 1 1 Initial and Maximum Number of Samples ocicicocococicinonononiononacinanononanananonononoso 2 20 2 15 1 2 Maximum Number of Bytes in Memory cocococioioononononnononinnoncnnonaninancnononananonononoso 2 21 2 15 2 Memory Management for a Sample ooococinnncccnnnnonicinonanoncnoncnn
94. ng the command line option remoteAdministrationDomainld see Table 4 1 RTI Queuing Service Com mand Line Options or the XML tag lt administration gt lt domain id gt see Configuring Administration Section 3 3 3 LJ Assigning an application name to each one of the Queuing Service instances using the command line option appName see Queuing Service runs as a separate application The script to run the executable is in lt NDDSHOME gt bin There are four ways to start Queuing Service Section This name should have a common prefix so that when an application sends a remote administration command that command can be applied to all the instances by selecting a target queuing service using a wildcard expression on the common prefix For example supposed you have three service instances with application names Cluster_1_Instance_1 Cluster 1 Instance 2 and Cluster 1 Instance 3 Notice that the word Cluster is not strictly required any common prefix will work To send a remote administration command to all three instances you can use Cluster_1 as the tar get queuing service IJ Setting the tag lt configuration_replication gt under service gos gt in the configuration file see SharedReaderOueue for Configuration Replication Section 7 2 1 This will cre ate a special SharedReaderOueue for configuration replication that runs in its own DomainParticipant I Optional Using the cfgRemote command line option in combination
95. ng to different dispatch policies To configure a dispatch pol icy and its properties use the lt distribution gt tag under lt queue_qos gt see Table 3 15 Queue QoS Tags Round Robin Dispatch Policy without Explicit AueueConsumer Availability Feedback This dispatch mode uses a round robin approach to dispatch messages among the QueueCon sumers that have acknowledged all previous messages sent to them up to a specified threshold This dispatch mode does not require explicit feedback from the QueueConsumer For example with a threshold of zero samples are round robin ed among QueueConsumers that have acknowledged all previous samples that were sent to them With a threshold of 2 sam ples are round robin ed among QueueConsumers that have acknowledged all samples sent to them except up to 2 samples i e have acknowledged all all but one or all but two With a threshold of UNLIMITED 1 samples are round robin ed among all QueueConsumers regard less of the number of outstanding unacknowledged samples in each one of them 2 11 Selecting a OueueConsumer for a Sample 2 10 2 With this dispatch mode the threshold is set per SharedReaderOueue using the property UNACKED THRESHOLD For example lt distribution gt lt kind gt ROUND ROBIN lt kind gt lt property gt lt value gt lt element gt lt name gt UNACKED_THRESHOLD lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt
96. ngth 0 5 10 Accessing Oueuing Service from a Connext DDS application requester RequestDataWriter get matched subscriptions handles System Threading Thread Sleep 1000 System Console WriteLine Matched subscription Send create command WriteSample lt CommandRequest gt request reguester CreateReguestSample reguest Data service name OueuingService 1 reguest Data action CommandActionKind RTI SERVICE COMMAND ACTION CREATE reguest Data resource identifier domain participant DomainParticipant shared subscriber SharedSubscriber reguest Data string body str N lt shared reader gueue name SharedReaderQueue_1 session session gt n lt topic_name gt SharedReaderQueueTopic lt topic_name gt 1n lt type name gt SharedReaderQueueType lt type name gt n lt shared_reader queue gt 1 requester SendRequest request Receive the reply Sample lt CommandReply gt reply reguester CreateReplySample if requester ReceiveReply reply MAX WAIT System Console WriteLine Received reply reply Data string body throw new SystemException Reply not received finally finally requester Dispose participant delete contained entities DomainParticipantFactory get_instance delete participant ref participant 5 11 Chapter 6 Publish Subscribe Monitoring of Queuing 6 1 Servic
97. nsitive unless otherwise stated L Comments are enclosed as follows lt comment gt L The root tag of the configuration file must be lt dds gt and end with lt dds gt Queuing Service provides an XSD file that describes the format of the XML content We recom mend including a reference to this file in the XML file that contains the Queuing Service configu ration this provides helpful features in code editors such as Visual Studio and Eclipse including validation and auto completion while you are editing the XML file The XSD definition of the XML elements is in lt NDDSHOME gt resource schema rti_queuing_service xsd To include a reference to the XSD document in your XML file use the attribute xsi noN amespaceSchemaLocation in the lt dds gt tag For example lt xml version 1 0 encoding UTF 8 gt lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespace SchemaLocation lt Queuing Service installation directory gt resource schema rti gueuing service xsd gt 3 3 XML Tags for Configuring Queuing Service lt dds gt 3 3 XML Tags for Configuring Queuing Service This section describes the XML tags you can use in a Queuing Service configuration file The fol lowing diagram and Table 3 1 describe the top level tags allowed within the root lt dds gt tag See Chapter 15 in the RTI Connext DDS Core Libraries User s Manual Optional See Configuring Queuing Service Types
98. nsumer Default false Oorl lt sample_timeout gt Configures the maximum amount of time that a sample can be in a replica s SharedReaderQueue without having reached quorum After this time the sample is removed from the SharedReaderQueue the replica sends an AppAck message to the QueueProducer with the response set to 0 and the rep lica notifies the master about this event Notice that the sample is not sent to the DeadLetterSharedReaderQueue This timeout is needed to avoid situations in which a sample stays in the replicas SharedReaderQueues permanently This could happen if for some reason one of the replicas participat ing in the quorum did not receive a sample from the Queue Producer Under this circumstance the sample would not be able to be enqueued with quorum and it would stay in the SharedReaderQueues of the replicas that received the sample indefinitely Default 7 seconds measured from the enqueue time Oorl 7 6 Configuration Replication 7 2 7 2 1 Configuration Replication By default the service configuration is not replicated Enabling configuration replication between a set of Queuing Service instances replication cluster will require I Enabling remote administration and using the same remote administration domain ID for each one of the Queuing Service instances participating in the configuration replication process The administration domain ID can be configured usi
99. nt enabled by default message is optional and can be disabled on a per SharedReaderQueue basis by setting the tag lt app_ack_sample_to_producer gt under lt queue_qos gt lt reliability gt to false see Table 3 15 Queue QoS Tags Samples are successfully processed when they are stored in the SharedReaderQueue Samples are rejected when they cannot be stored in the SharedReaderQueue One possible cause of rejection is when the maximum number of samples that can be stored in the queue is exceeded The response data of the AppAck message for successfully processed samples will be a single byte set to 1 The response data for rejected samples will be a single byte set to 0 You may want to capture the AppAck message by installing a listener on the DataWriter that implements the on application acknowledgment callback AueueProducer Wrapper To simplify the use and configuration of a DataWriter to send samples to a SharedReaderOueue Connext DDS provides an abstraction QueueProducer lt aMessageType gt that wraps the DataW riter and provides additional services such as an operation to detect if there is a matching Share dReaderQueue or an operation to wait for application level acknowledgement after sending a sample For more information see Chapter 8 Queuing Service Wrapper API Note In this release the QueueProducer wrapper API is only supported in the NET API Samples with Large Maximum Size By default Connext DDS pr
100. nter this all on one line SNDDSHOMES resource app bin x64Win64VS2008 nssm exe set rtiqueuingservice520 AppParameters cfgFile C dir with spaces qsconf with vars xml cfgName MyCustomConf var MY DOMAIN 10 7 If a variable value includes spaces you must enclose the value in escaped quotes For example you would enter this all on one line SNDDSHOME resource app bin x64Win64VS2008 nssm exe set rtiqueuingservice520 AppParameters cfgFile C dir with spaces qsconf with vars xml cfgName MyCustomConf var NAME My QS name I If you use environment variables instead of the var command line option you may need to restart your Windows machine I If you specify cfgFile in the Start Parameters field you must use the full path to the file L Some versions of Windows do not allow Windows Services to communicate with other services applications using shared memory For this reason if you plan to run Queuing Service as Windows Service you should disable the shared memory transport in all the DomainParticipants created by Queuing Service and in the applications communicating with Queuing Service For more information on setting builtin transports see the RTI Con next DDS Core Libraries User s Manual Section 15 1 Builtin Transport Plugins LJ In some scenarios you may need to add a multicast address e g builtin udpv4 239 255 0 1 to your discovery peers For details on setting the discovery peers see the RTI C
101. o the maximum number of samples or maximum number of bytes allowed in the SharedReader Queue For example lt resource limits gt lt gueue allocation settings gt lt max_count gt 1000 lt max_count gt lt max in memory bytes gt 10000000 lt max in memory bytes gt lt gueue allocation settings gt lt queue_watermark_settings gt lt high_watermark gt 90 lt low_watermark gt lt low watermark gt 10 lt low watermark gt lt gueue watermark settings gt lt resource_limits gt In the above example the high watermark of 90 corresponds to 900 samples 9 000 000 bytes and the low watermark of 10 corresponds to 100 samples 1 000 000 bytes 2 22 SharedReaderQueue Resource Management 2 15 4 An application can monitor if the number of samples in a SharedReaderQueue go over the high watermark or below the low watermark by retrieving the SharedReaderQueue status using the remote administration command Get SharedReaderQueue Status see Get SharedReaderQueue Status Section 5 4 4 or by subscribing to the SharedReaderQueue status monitoring topic see Chapter 6 Publish Subscribe Monitoring of Queuing Service from a Remote Location The SharedReaderQueueStatus type used to provide the status of a SharedReaderQueue can be found lt NDDSHOME gt resource idl QueuingServiceTypes idl struct SharedReaderQueueStatus unsigned long long high watermark count unsigned long long low watermark count unsigned long long queue full
102. obtain its initial configuration remotely from a different Queuing Service instance by using the cfgRemote command line option see Table 4 1 Before reading this chapter you should be familiar with Terms to Know Section 2 1 This chapter describes I How to Load the XML Configuration from a File Section 3 1 LJ XML Syntax and Validation Section 3 2 LJ XML Tags for Configuring Queuing Service Section 3 3 How to Load the XML Configuration from a File Queuing Service loads its XML configuration file s from multiple locations This section presents the various approaches listed in load order The first three locations only contain QoS Profiles and are inherited from Connext DDS see Chapter 15 in the RTI Connext DDS Core Libraries User s Manual LJ lt NDDSHOME gt resource xml NDDS_QOS_PROFILES xml This file contains the Connext DDS default QoS values it is loaded automatically if it exists First to be loaded T File in NDDS_QOS_PROFILES The files or XML strings separated by semicolons referenced in this environment vari able are loaded automatically LJ lt working directory gt USER_QOS_PROFILES xml This file is loaded automatically if it exists 3 1 How to Lond the XML Configuration from a File The next locations are specific to Oueuing Service LJ lt NDDSHOMB gt resource xml RTI_QUEUING_SERVICE xml This file contains the default Queuing Service configuration it is loaded if it exists RT
103. ome your user namelrti connext dds version e UNIX based systems root user lopt rti connext dds version e Windows systems user without Administrator privileges lt your home directory gt rti_connext_dds version e Windows systems user with Administrator privileges C Program Files rti_connext_dds version for 64 bits machines or C Program Files x86 rti_connext_dds version for 32 bit machines You may also see NDDSHOME or NDDSHOME which refers to an environment variable set to the installation path Wherever you see lt NDDSHOME gt used in a path replace it with your installation path Note for Windows Users When using a command prompt to enter a command that includes the path C Program Files or any directory name that has a space enclose the path in quotation marks For example C Program Files rti_connext_dds version bin rtiddsgen or if you have defined the NDDSHOME environment variable SNDDSHOMES bin rtiddsgen J RTI Workspace directory rti_workspace The RTI Workspace is where all configuration files for the applications and example files are located All configuration files and examples are copied here the first time you run RTI Launcher or any script in lt NDDSHOME gt bin The default path to the RTI Work space directory is e Mac OS X systems Users your user name rti_workspace 2 2 Load Balancing by Sharing a Oueue 2 3 e UNIX based systems home your user namelrti work
104. onitoring Tags mm Number Tags within dE f lt entity_monitoring gt a A o ar amp Allowed Enables disables remote publish subscribe monitoring for a given lt enabled gt entity If general monitoring is disabled this value is ignored Oorl Default value true Specifies the frequency at which the status of an entity is published For example lt status_publication_period gt lt sec gt 3 lt sec gt lt status_publication_period gt lt nanosec gt 0 lt nanosec gt 0or1 lt status publication period gt If the tag is not defined its value is inherited from the general mon itoring settings 3343 Configuring Statistics Calculation Process Queuing Service reports multiple statistics as part of the entity status Some of these statistics are counters such as the number of samples received by a SharedReaderQueue other statistics are statistics variables such as the number of samples enqueued per second in a SharedReader Queue struct SharedReaderQueueStatus unsigned long long received message count StatisticVariable engueue throughput For a given statistic variable Queuing Service computes the metrics in StatisticMetrics during specified time frames struct StatisticMetrics unsigned long long period_ms long long count float mean float minimum float maximum float std_dev struct StatisticVariable StatisticMetric publication period metricg seguence lt StatisticMetrics MAX
105. onnext DDS Core Libraries Getting Started Guide Section 4 1 2 How to Set Your Dis covery Peers Stopping Queuing Service when it is Running as a Windows Service To stop Queuing Service when it is running as a Windows Service use this command sc rtiqueuingservice520 stop You can also start stop Queuing Service from the Windows Services Control Manager From the Start menu select Control Panel Administrative Services Services Click on the service in the list then right click to select Start or Stop Disabling Queuing Service from Running as a Windows Service To remove Queuing Service from the list of Windows Services on your system run this command in a terminal with Administrator privileges lt NDDSHOME gt bin rtiqueuingservice uninstallService By default the service rtiqueuingservice520 is uninstalled If you want to uninstall a different service instance add the serviceName option to the above command 4 5 Chapter 5 Administering Queuing Service from a 5 1 5 2 Remote Location Queuing Service can be controlled remotely by sending commands through a special topic Any Connext DDS application can be implemented to send these commands and receive the corre sponding responses Enabling Remote Administration By default remote administration is disabled in Queuing Service for security reasons To enable remote administration you can use the lt administration gt tag see Configuring Administration Sect
106. onos 7 1 7 1 1 SharedReaderOueue Replication ProtocOl rrteeerteneneersresisssss 7 1 71 11 Sample Replication Phaser idilio diles 7 2 7 1 1 2 Enqueue Phaser dette nih ania Ae Sin lha Gee ta 7 3 7 1 1 3 Consumer Assignment Phase 7 4 71 14 gt Delivery Phases iii A A a ta 7 4 7 1 2 SharedReaderQueue Master Election Protocol ooocccnoonononoonoonnnoncononnccononoconnononoononnnnnnco noo 7 4 7 13 SharedReaderOueue Replication Configuration imrersesenerenenenenenenennanenenei 7 5 7 1 3 1 Protocol Information Exchange cococnocncnnnnoninnncnnononnnncnnonororonnncanconorornn nino ronancininnos 7 6 72 Configuration Replicar e as a LOANS odds iii aaa eset 7 7 7 2 1 SharedReaderQueue for Configuration Replication eereeeereerseeseeeresesessesssssessesses 7 7 197 Replication Clusters pie 15 80 seek aoaaa ah take EEE E Errata e ekat nd aaa kee 0 7 8 Queuing Service Wrapper API nnrrrrnrnnnannannannnna 8 1 8 1 QueueProducer Wrapper cc s2 2scncskeciieesst in av EL oid baa cet akte bi ds 8 1 8 2 QuetieConsumer Wrappetices i csscsrisiestecvsesersers sects cabs caste habe cesed se shk onu KD da ais sag a Sh SUE shade ga 8 1 8 3 OueueReguester Wrapper cccccccsesececesssseessesetessesessesseseecscsesececsesesessesesesenesesecsssesesaesesesseaeesesneeseaeeeees 8 1 8 4 Qu ueReplier WIapp r iii io 8 2 Communication Using TCP Transport ccc
107. or For example you can specify a filter so that only certain types of log messages are published For details see the RTI Distributed Logger Getting Started Guide 3 27 Chapter 4 Running Queuing Service Queuing Service runs as a separate application The script to run the executable is in lt NDDSHOMEB gt bin There are four ways to start Queuing Service I Starting from Launcher Section 4 1 LJ Starting Manually from the Command Line Section 4 2 I Using Queuing Service as a Windows Service Section 4 3 If you are starting Queuing Service as a Windows Service also read Notes when Running as a Windows Service Section 4 3 3 4 1 Starting from Launcher 1 Start RTI Launcher from the Start menu on Windows systems or on the command line type lt NDDSHOME gt bin rtilauncher 2 From the Services tab select Queuing Service Third Party Help _ Installation JOE Routing Service Recording Service Replay Service Persistence Service aA 4 1 Starting Manually from the Command Line 4 2 Starting Manually from the Command Line To start Queuing Service enter cd lt NDDSHOME gt bin rtigueuingservice options Example cd lt NDDSHOME gt bin rtigueuingservice cfgFile example xml cfgName OueuingService 1 Table 4 1 describes the command line options Table 4 1 RTI Queuing Service Command Line Options Option Description appName lt
108. or lt rep lication gt under lt gueue gos gt for SharedReaderQueues e lt configuration_replication gt under lt service_qos gt for configuration See Chapter 7 High Availability Oorl lt service_qos gt Configures the QoS for the service See Table 3 3 Service QoS Tags Oorl lt statistics gt Configures the statistics gathering process for publish subscribe and request reply monitoring See Configuring Monitoring Section 3 3 4 Oorl 3 3 3 Configuring Administration You can create a Connext DDS application that can remotely control Queuing Service The lt administration gt tag is used to enable remote administration and configure its behavior By default remote administration is turned off in Queuing Service for security reasons A remote administration section is not required in the configuration file For example lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti_queuing_service xsd gt lt queuing service name OueuingService 1 gt lt administration gt lt domain_id gt 55 lt domain_id gt lt administration gt lt gueuing service gt lt dds gt 3 7 XML Tags for Configuring Queuing Service Table 3 3 Service QoS Tags Number Tags within lt service gos gt Description of Tags Allowed lt configuration_replication gt Enables configuration replication See Chapter7 High Availability 0or1
109. oring and request reply monitoring are turned off in Queuing Service for security and performance reasons A lt monitoring gt or lt administra tion gt section is not required in the configuration file For example lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti queuing service xsd gt lt queuing service name QueuingService_ 1 gt lt administration gt lt domain_id gt 55 lt domain_id gt lt administration gt lt monitoring gt lt domain_id gt 55 lt domain_id gt lt monitoring gt qe ess lt dds gt There are two kinds of monitoring data for en entity for example a SharedReaderQueue I Entity data I Entity status Entity data provides information about the configuration of the entity For example the service data contains a list of the SharedReaderQueues contained in the service Entity data information is updated every time there is a configuration change that affects that data Entity status provides information about the operational status of an entity This kind of infor mation changes continuously and is computed and published periodically For example the SharedReaderQueue status contains information such as the SharedReaderQueue s latency and throughput The following table shows the monitoring information available with publish subscribe and request reply monitoring Publish Subscribe Request Reply ServiceData No Yes SharedReade
110. ory prefix topicName sharedSubscriberName domainId appName _m fileIndex db Where SharedReaderQueue Resource Management 2 14 2 1 2 15 2 15 1 2 15 1 1 I directory is configured using the tag lt directory gt under lt persistence_settings gt lt file system gt LI prefix is configured using the tag file prefix gt under lt persistence_settings gt lt filesys tem gt I appName is configured using the command line parameter appName Ll topicName is configured using the tag value topic name gt under lt shared_reader_queue gt 1 sharedSubscriberName is configured using the attribute name under lt shared_subscriber gt Ll domain id is configured using the tag value lt domain id gt under lt domain_participant gt IJ fileIndex is the index of the file containing data or metadata This index always increases and Queuing Service creates a new file after lt filesystem gt lt file_max_size gt is reached see Table 3 9 Filesystem Tags The Restore Process Before the samples for a SharedReaderQueue are restored the service instance will preprocess them as follows See Sample Lifecycle In Queuing Service Section 2 9 for more information I If there is no DeadLetterSharedReaderQueue the service will remove expired samples from disk based on the expiration time set when the samples were first added to the SharedReaderQueue LJ If there is no DeadLetterSharedReaderQueue the
111. ow to configure the TCP transport in Queuing Service For convenience the participant QoS in the administration and SharedReaderQueue domains inher its from a commom QoS profile TCPLibrary TCPProfile lt gos library name TCPLibrary gt lt gos profile name TCPProfile gt lt participant goS gt lt property gt lt value gt lt element gt lt name gt dds transport load plugins lt name gt lt value gt dds transport tcp lt value gt lt element gt lt element gt lt name gt dds transport tcp library lt name gt lt value gt nddstransporttcp lt value gt lt element gt lt element gt lt name gt dds transport tcp parent classid lt name gt lt value gt NDDS TRANSPORT CLASSID TCPV4 WAN lt value gt lt element gt lt element gt lt name gt dds transport tcp create function lt name gt lt value gt NDDS Transport TCPv4 create lt value gt lt element gt lt value gt lt property gt lt participant_qos gt lt qos_profile gt lt gos library gt lt queuing Service name Service gt lt administration gt lt domain id gt 1 lt domain id gt lt participant dos base name TCPLibrary TCPProfile gt lt property gt lt value gt lt element gt Asymmetric TCP Communication With Oueuing Service lt name gt dds transport tcp server bind port lt name gt lt value gt 15001 lt value gt lt element gt lt element gt lt name gt dds transport tcp public address lt name gt lt value gt 18
112. p hex 000000000000000000000000000000EF Sample with related_reader_guid OxFF Sample with related_reader_guid OxEF DW DataWriter DR DataReader CFT ContentFilteredTopic In Figure 2 3 when Queuing Service wants to send a sample to the first DataReader it sets the field related_reader_guid in WriteParams t to 0xFF To send to the second DataReader related reader guid is set to OxEF Interaction of Publish Subscribe Entities with Queuing Service Entities A regular DataReader of Topic aQueueTopicName aSharedSubscriberName will match a SharedReaderQueue DataWriter for the SharedSubscriber aSharedSubscriberName of Topic aQueueTopicName However Queuing Service will notice that the DataReader s SharedSubscrib erName is not set and interpret this to mean that it does not want to share the ReaderQueue Instead the DataReader wants traditional publish subscribe access which means it will get a copy of each sample that is sent to any of the QueueConsumers See Figure 2 4 This approach ensures that RTI DDS Spy RTI Recording Service and other such tools that observe data will continue to function without changes Note that the QueueProducer has a regular DataWriter of Topic aQueueTopicName In addition to the SharedReaderQueue DataReader it will also match any regular DataReader of that Topic 2 8 Sample Lifecycle In Queuing Service Consequently the regular Connext DDS tools such as RTI DDS Spy and RTI Recordin
113. pant Tags which affects all the SharedReaderQueues within the lt domain_participant gt For example memory management gt lt sample buffer min size gt 16000 lt sample buffer min size gt lt sample buffer trim to size gt true lt sample buffer trim to size gt lt memory management gt In the above example L sample buffer min size If the serialized size of an incoming sample is smaller or equal to 16000 bytes Queuing Service will use a pre allocated buffer from a pool to hold the sample The initial and maximum number of buffers in the pool as well as the pool s growth policy is configured using the XML tag lt resource limits gt under lt shared_reader_queue gt lt queue_qos gt When the serialized size of the incoming sample is greater than 16 000 bytes Queuing Service will allocate the buffer from the heap dynam ically upon sample reception L sample buffer trim to size For dynamically allocated buffers Queuing Service will release the memory after the sample is removed from the SharedReaderOueue For more information on memory management and its default values see Table 3 10 DomainParticipant Tags High and Low Watermarks The tag lt queue_watermark_settings gt under shared reader gueue gt lt gueue gos gt lt resource limits gt can be used to configure high and low watermarks in a SharedReaderQueue see Table 3 15 Queue QoS Tags Watermarks are expressed as a percentage with respect t
114. pecially with the usage of multicast See Figure 7 2 Figure 7 2 Direct Sample Distribution Queuing Service 1 Queuing Service 2 7 2 SharedReaderOueue Replication 2 The QueueProducer s DataWriter sends the samples to only a subset of the replicas usu ally one Then the replicas that receive the samples broadcast these samples to all the other replicas as seen in Figure 7 3 Figure 7 3 Relayed Sample Distribution 7 1 1 2 Queuing Service 1 Se cote LTE Queuing Service 2 ga lii Queuing Service 3 vei Y siiis In this release the decision of whether or not a replica should broadcast the received samples to the other replicas is taken by the OueueProducer s application on a per sample basis by marking the sample with the flag DDS REPLICATE SAMPLE This can be done by using the DataW riter s write w params operation and setting the bit DDS REPLICATE SAMPLE in the flag field of WriteParams_t Engueue Phase During the enqueue phase the master makes sure at least a quorum of the most up to date rep licas including itself have received a sample before moving the sample to the ENQUEUE state see Sample Lifecycle In Queuing Service Section 2 9 The number of replicas in the quorum is defined as the lowest integer that is higher than half of the expected number of replicas The expected number of replicas must be known in advance and it is configured using the XML tag lt que
115. rQueue When the slaves receive this noti fication they also remove the sample from their SharedReaderQueues SharedReaderQueue Master Election Protocol When the master for a SharedReaderQueue goes away the most up to date slave is promoted into master How fast the loss of the master is detected depends on a master timeout period configurable using the XML tag lt master_timeout gt under lt replication_settings gt See SharedReaderQueue Replication Configuration Section 7 1 3 If a slave does not receive messages from the master during a period greater than the master timeout it initiates a voting mechanism to select a new master While the new master election is in progress the samples sent by QueueProducers will be rejected The QueueProducer will receive AppAck messages from all replicas with the response set to 0 7 4 SharedReaderOueue Replication 7 1 3 Table 7 1 Table 7 2 SharedReaderQueue Replication Configuration You can choose between replicating all the SharedReaderQueues within a service or replicating individual SharedReaderQueues To replicate all the SharedReaderQueues within a service you can set the lt shared reader gueue replication gt tag within lt gueuing service gt lt service gos gt Replica tion is automatically enabled when you use this tag It also allows you to configure the replica tion protocol Table 7 1 SharedReaderQueue Replication Tags describes the tags allowed within
116. rQueueData No Yes SharedReaderQueueStatus Yes Yes XML Tags for Configuring Queuing Service 3 3 4 1 3 3 4 2 For more information on how to retrieve the monitoring data see Chapter 5 Administering Queuing Service from a Remote Location and Chapter 6 Publish Subscribe Monitoring of Queuing Service from a Remote Location Configuring Request Reply Monitoring See Configuring Administration Section 3 3 3 Configuring Publish Subscribe Monitoring When publish subscribe remote monitoring is enabled Queuing Service will create one Domain Participant one Publisher and one DataWriter to publish SharedReaderQueue status You can configure the QoS of these entities with the lt monitoring gt tag defined under lt queuing_service gt Table 3 5 Monitoring Tags T ee Number ags within Description of Tags lt monitoring gt P A d Enables disables publish subscribe monitoring for the Queuing Service instance Setting this value to true default value in the lt monitoring gt tag under lt gueuing service gt enables monitoring in all the entities enabled unless they explicitly disable it by setting this tag to false in their local lt entity_monitoring gt tags Dor1 Setting this tag to false in the lt monitoring gt tag under lt gueuing service gt disables monitoring in all the Queuing Service entities In this case any monitoring configuration settings in the entities are ignored Default value
117. remote command to create a SharedReaderOueue The reguest receives a reply with the result for that command using using using using using using using System System Collections Generic System Text RTI Service Admin DDS RTI Connext ReguestReply RTI Connext Infrastructure How to use the Oueuing Service administration through a Reguester public class CommandExample private static readonly Duration_t MAX WAIT Duration t from seconds 10 public static void Main string args Create DomainParticipant DomainParticipant participant DomainParticipantFactory get instance create participant 1 DomainParticipantFactory PARTICIPANT QOS DEFAULT null StatusMask STATUS MASK NONE if participant null throw new SystemException Participant creation failed try Accessing Queuing Service from a Connext application Create requester for Routing Service remote admin topics Requester lt CommandRequest CommandReply gt requester new Requester lt CommandRequest CommandReply gt new RequesterParams participant CommandReguestTypeSupport get instance CommandReplyTypeSupport get instance SetReguestTopicName COMMAND REQUEST TOPIC NAME VALUE SetReplyTopicName COMMAND REPLY TOPIC NAME VALUE try System Console WriteLine Waiting to discover Oueuing Service InstanceHandleSeg handles new InstanceHandleSeg while handles le
118. ror Delete SharedReaderQueue The following command is used to delete a SharedReaderQueue DELETE target gueuing services shared reader queue resource identifier gt Return Value Upon success this command returns RTI_SERVICE_COMMAND_REPLY_OK in the retcode field of the reply Otherwise this command returns RTI SERVICE COMMAND REPLY ERROR and the field string body contains a human readable string describing the error Flush SharedReaderQueue The following command is used to flush all the samples or a set of samples from a SharedRead erQueue DELETE lt target gueuing services shared reader queue resource identifier gt message lt sample selector gt Parameters The lt sample selector gt see Sample Selector Section 5 2 2 is a SOL expression that specifies the set of samples that must be removed and it must be provided in the field string body of the CommandReguest Return Value Upon success this command returns RTI SERVICE COMMAND REPLY OK in the retcode field of the reply Otherwise this command returns RTI SERVICE COMMAND REPLY ERROR and the field string body contains a human readable string describing the error Get SharedReaderQueue Status The type of the SharedReaderOueue s status is called SharedReaderOueueStatus you can find it in the file lt NDDSHOME gt resource idl QueuingServiceTypes idl The operational status provides multiple counters describing the status of the SharedRea
119. s For each lt domain_participant gt tag Queuing Service creates one DomainParticipant to communi cate over DDS Table 3 10 DomainParticipant Tags lists the tags allowed within lt domain_participant gt 3 14 XML Tags for Configuring Queuing Service Table 3 7 Statistics Tags Tags within lt statistics gt Description Number of Allowed Tags lt historical_statistics gt Enables or disables the statistic calculation within fixed time windows By default Queuing Service only publishes the statistics corre sponding to the window between two status publications By using this tag you can get the following additional windows e 5seconds e 1 minute e 5 minutes e 1 hour e Up time since the entity was enabled For example lt historical_statistics gt lt five second gt true lt five second gt lt one minute gt true lt one minute gt lt five minute gt false lt five minute gt lt one hour gt true lt one hour gt lt up_time gt false lt up_time gt lt historical statistics gt If a window is not present inside lt historical statistics gt it is considered disabled Historical statistics can be overridden on a per entity basis Oorl lt statistics sampling period gt Specifies the freguency at which statistics variables such as throughput and latency are updated For example lt statistics sampling period gt lt sec gt 1 lt sec gt lt nanosec gt 0 lt nanosec gt
120. s 2 2 2 3 Load Balancing by Sharing a Queue ococccicicocononincnononecnonanancnnanncnonononononononanononon anar onononon oran onon on cn na nnnnnnos 2 3 2 4 DataWriter Connection to a SharedReaderOueue ocoococcoonconcnononnnonnonnncononncco non ccoo non ocoonco nan nnno nan nonnnnns 2 4 2 4 1 QuewveProduc r Wrapper aiii ceiba 2 5 2 4 2 Samples with Large Maximum Size 2 5 2 5 DataReader Connection to a SharedReaderQueue cccccessecsscssecsscsseeecesceeceeeeseseeeeseseeeeeeseeseeess 2 5 2 9 1 OueveCorisumer Wrappetssiciacicick casei caleta sacs dd 2 6 2 5 2 Samples with Large Maximum Size 2 6 2 0 Queuing Service Bt tes acacia sort tem M ak esu Jausa Saavad Ghia EEs LEDa i ERa AOA S aE ses 2 6 2 7 Sample Distribution to a Selected QUeUCCONSUMET iiimiesreneneeneneneneenaneneneneaneeeneneeeenet 2 7 2 8 Interaction of Publish Subscribe Entities with Queuing Service Entities 2 8 2 9 Sample Lifecycle In Queuing Service mesnega iai ea ies aiaiai ina kadh viirit is oiaoi 2 9 2 10 Selecting a OueueConsumer for a Sample nsnenereresnenerereresrererenersnenenerenersnenerensi 2 11 2 10 1 Round Robin Dispatch Policy without Explicit QueueConsumer Availability Feedback eine e a e e i 2 11 2 10 2 Round Robin Dispatch Policy with Explicit QueueConsumer Availability Feedback meneren detal E EE E E E A 2 12 2 11 Sending a Reply from QueueConsumer to QueueProducer mimienenene
121. s are persisted as well as the properties of the storage process can be configured using the lt filesystem gt tag under lt gueuing service gt lt persistence settings gt see Configuring Per sistence Settings Section 3 3 5 When a SharedReaderOueue is created the service will locate its persisted samples using the following values L Command line option appName see Queuing Service runs as a separate application The script to run the executable is in lt NDDSHOME gt bin There are four ways to start Oueuing Service Section L XML tag values lt directory gt and file prefix gt under lt persistence_settings gt lt filesys tem gt LJ The SharedSubscribers name configured using the name attribute in lt shared_subscriber gt L The SharedReaderQueue s topic name configured using the XML tag value lt topic_name gt under lt shared_reader_queue gt L The DomainParticipant s domain ID configured using the XML tag value lt domain_id gt under lt domain_participant gt If the samples are found the SharedReaderQueue will be initialized with them The location and name of the file where the SharedReaderQueue s samples are persisted is as follows L Without in memory state directory prefix topicName shared Subscriber Name domainId appName db LI With in memory state For data directory prefix topicName shared SubscriberName domainId appName _d fileIndex db For metadata direct
122. source to which the action is applied see Resource Identifiers Section 5 2 1 LJ lt body gt identifies the parameters of the action on the resource identified by lt resource_identifier gt For example when creating a SharedReaderQueue the body is the XML snippet for the new queue 5 2 1 Resource Identifiers The format of a resource identifier is as follows lt resource_kind_1 gt lt resource_name_1 gt lt resource_kind_N gt resource_name_N Where I lt resource kind gt can have one of the following values e domain participant shared subscriber shared reader gueue dead letter shared reader gueue status data and message The resource kinds status data and message represent different information for an entity e status Refers to the operational status for a Queuing Service entity This informa tion changes continuously The status information is composed primarily of statis tics e data Refers to configuration data This data is mostly static and does not change continuously e message Applies to SharedReaderQueues and refers to samples in the queues 1 lt resource_name gt specifies the name of the resource as defined in the XML configuration file using the attribute name For example consider the following XML lt xml version 1 0 gt lt dds gt lt queuing service name QueuingService_1 gt lt domain participant name DomainParticipant_1 gt shared subscriber name SharedSu
123. space e Windows systems your Windows documents folderXrti workspace Note your Windows documents folder depends on your version of Windows For example on Windows 7 the folder is C Users your user name Documents on Windows Server 2003 the folder is C Documents and Settings your user name Documents You can specify a different location for the rti_workspace directory See the RTI Connext DDS Core Libraries Getting Started Guide for instructions I path to examples Examples are copied into your home directory the first time you run RTI Launcher or any script in lt NDDSHOME gt bin This document refers to the location of these examples as lt path to examples gt Wherever you see lt path to examples gt replace it with the appropri ate path By default the examples are copied to rti_workspace version examples So the paths are e Mac OS X systems Users your user namelrti workspace version examples e UNIX based systems home your user name rti_workspace version examples e Windows systems your Windows documents folder rti_workspace version examples Note your Windows documents folder is described above You can specify that you do not want the examples copied to the workspace See the RTI Connext DDS Core Libraries Getting Started Guide for instructions Load Balancing by Sharing a Queue A DDS DataReader has an ingress ReaderQueue that stores received samples The DataReader can perform a take operation
124. ssociated with the session DDS Subscribers avi lt subscriber_qos gt There is one Subscriber per session 3 3 8 Configuring Session Settings Table 3 12 Session Settings Tags lists the only tag allowed within lt session_settings gt Table 3 12 Session Settings Tags T za Number ags within Descrivti A A escription of Tags lt session_settings gt Allowed A session defines a threaded context for a SharedReaderOueue 1 or more lt session gt i See Configuring SharedSubscribers Sessions Section 3 3 9 reguired 3 3 9 Configuring SharedSubscribers Sessions A session defines a threaded context for a SharedReaderOueue SharedReaderOueues in differ ent sessions can be processed in parallel Sessions are part of SharedSubscribers For each Session defined within the tag session settings gt Queuing Service will create the fol lowing elements 4 Two threads one for storing samples into SharedReaderQueues and one to distribute samples from the SharedReaderQueues to QueueConsumers 1 One DDS Publisher 1 One DDS Subscriber The QoS of the Publisher and Subscriber are configured using the tags lt publisher_qos gt and lt subscriber_qos gt under lt shared_subscriber gt Table 3 13 Session Tags lists the tags allowed within lt session gt 3 19 XML Tags for Configuring Oueuing Service SharedReaderOueues and DeadLetterSharedReaderOueues can be associated with a session b
125. t participant_qos gt lt configuration_replication gt lt service_qos gt lt domain participant name DomainParticipant gt domain id gt 0 lt domain id gt lt participant dos base name TCPLibrary TCPProfile gt lt property gt lt value gt lt element gt lt name gt dds transport tcp server bind port lt name gt lt value gt 15000 lt value gt lt element gt lt element gt lt name gt dds transport tcp public address lt name gt 9 6 Asymmetric TCP Communication with Oueuing Service And Replication lt value gt 18 181 0 32 15000 lt value gt lt element gt lt element gt lt name gt dds transport tcp2 server bind port lt name gt lt value gt 15001 lt value gt lt element gt lt element gt lt name gt dds transport tcp2 public address lt name gt lt value gt 192 168 5 11 15001 lt value gt lt element gt lt value gt lt property gt lt participant goS gt lt domain participant gt lt gueuing services The following XML snippet shows how to configure the applications running outside the NAT lt participant goS gt lt property gt lt value gt lt element gt lt name gt dds transport load plugins lt name gt lt value gt dds transport tcp lt value gt lt element gt lt element gt lt name gt dds transport tcp library lt name gt lt value gt nddstransporttcp lt value gt lt element gt lt element gt lt name gt dds transport tcp parent classid lt name gt l
126. t value gt NDDS TRANSPORT CLASSID TCPV4 WAN lt value gt lt element gt lt element gt lt name gt dds transport tcp create function lt name gt lt value gt NDDS Transport TCPv4 create lt value gt lt element gt lt element gt lt name gt dds transport tcp server bind port lt name gt lt value gt 0 lt value gt lt element gt lt value gt lt property gt lt participant_qos gt 9 7
127. that host SharedReaderQueues allowing remote QueueCon sumers to attach to the shared gueues and providing exactly once or at most once access to the samples in the shared queues With these access modes when one QueueConsumer gets a message the other QueueConsum ers attached to the same SharedReaderQueue do not get that message A SharedSubscriber can host one or more SharedReaderQueues each one associated with a different DDS Topic name Table 3 11 lists the tags allowed within lt shared_subscriber gt XML Tags for Configuring Queuing Service Table 3 11 SharedSubscriber Tags bt Number Tags within age Description of Tags lt shared_subscriber gt Allowed lt dead_letter_shared_reader_queue gt You can define one dead letter queue per SharedSub 0 or 1 Configures the DeadLetterSharedReaderQueue for a SharedSubscriber scriber See Dead Letter Queues Section 2 12 Sets the QoS associated with the session DDS Publishers Publisher gos There is one Publisher per session ol Configures the sessions for the SharedReaderOueues defined in the SharedSubscriber lt session_settings gt A session defines a threaded context for a SharedReader 1 required Queue See Configuring Session Settings Section 3 3 8 Configures a SharedReaderQueue in a SharedSubscriber lt shared_reader_queue gt AIA 0 or more See Configuring SharedReaderOueues Section 3 3 10 Sets the OoS a
128. tionBuiltinTopicData include a field called ser vice which in the case of a Queuing Service DataWriter or DataReader is set to OUEUING SERVICE OOS Since the durability of the QueueProducer DataWriter is normally set to VOLATILE to guaran tee that the initial samples are received by a Oueuing Service instance the application should check that there is a match between a OueueProducer DataWriter and a SharedReaderOueue DataReader before starting to publish samples For convenience and ease of use the wrapper APls offer methods to detect when there are matching SharedReaderOueue for QueueProducers QueueConsumers OueueReguesters and OueueRepliers See Chapter 8 Oueuing Service Wrapper API Queuing Service Persistency By default both the service state and the SharedReaderOueues samples are kept in memory For fault tolerance and to preserve the current configuration Oueuing Service can be configured to persist its configuration as well as the SharedReaderOueues samples to disk Figure 2 7 Service State Persistency 2 14 1 l gt Queuing Service i Filesystem Shared i Service Subscriber A configuration SharedReaderQueue 1 samples SharedReaderQueue 2 samples Service State Persistency The configuration of a Queuing Service instance is dynamic Once the service is bootstrapped from a configuration file in XML format or remotely by getting the configuration from other Oueuing Service
129. true Configures the DataWriter QoS for remote monitoring If the tag is not defined Queuing Service will use the Connext DDS lt datawriterq s defaults with this change gior durability kind DDS_TRANSIENT_LOCAL_DURABILITY_QOS Pe Specifies which domain ID Queuing Service will use to enable 1 lt domain_id gt ae remote monitoring required Configures the DomainParticipant QoS for remote monitoring Bie tnctat es If the tag is not defined Queuing Service will use the Connext DDS jail P Pores defaults with this change s resource limits type code max serialised length 4096 3 11 XML Tags for Configuring Oueuing Service Table 3 5 Monitoring Tags Number kd thin Description of Tags lt monitoring gt Allowed Configures the Publisher QoS for remote monitoring lt publisher_qos gt If the tag is not defined Queuing Service will use the Connext DDS 0 or 1 defaults Specifies the frequency at which the status of an entity is pub lished For example lt status publication periods lt sec gt 3 lt sec gt lt nanosec gt 0 lt nanosec gt ld f lt status publication period gt lt status publication period gt a 00r1 If the tag is not defined the period is 5 seconds The status publication period defined in lt gueuing service gt lt monitoring gt is inherited by all the monitorable entities within lt gueuing service gt An entity can override the period 3 3
130. true see Configuring Share dReaderQueues Section 3 3 10 Oorl 3 16 XML Tags for Configuring Queuing Service Table 3 9 Filesystem Tags Tags within se Number lt filesystem gt Description of Tags Allowed Determines the level of synchronization with the physical disk This tag can take three values e FULL Every sample is written to physical disk as Queuing Service lt synchronization gt vea lb Oorl yn e NORMAL Samples are written to disk at critical moments e OFF No synchronization is enforced Data will be written to physical disk when the OS flushes its buffers Default OFF Specifies the name of the trace file for debugging purposes The trace file contains information about all SQL statements executed by the persistence service lt trace_file gt Default No trace file is generated 0or1 Note This does not apply to PERSISTENT SharedReaderOueues cre ated with lt in memory state gt set to true see Configuring Share dReaderOueues Section 3 3 10 Sets the auto vacuum status of the storage This tag can take these val ues NONE When data is deleted from the storage files the files remain the same size lt vacuum gt e FULL The storage files are compacted every transaction 0or1 Default FULL Note This does not apply to PERSISTENT SharedReaderQueues cre ated with lt in_memory_state gt set to true see Configuring Share dReaderQueues Section 3 3 1
131. ue L FailedDelivery Indicates a sample that has not been successfully delivered to any QueueConsumer after the maximum number of attempts configured using the tag lt max_delivery_retries gt under lt queue_qos gt lt redelivery gt for a SharedReaderQueue see Table 3 15 Queue QoS Tags In addition to the state each sample has a flag that indicates whether the sample may be a dupli cate This flag is set when Queuing Service sends a sample to a QueueConsumer but cannot ensure that no other QueueConsumer has processed it You can inspect the status of the duplicate flag in a received sample by inspecting the field flag in the Samplelnfo A sample may be a duplicate if the bit DDS REDELIVERED SAMPLE is active State Transitions State s Transition Event to Next State Next State lt Init gt Sample is received by SharedReaderQueue DataReader and stored in the SharedReaderQueue If SharedReaderQueue replication is enabled sample is received and stored by a quorum of up to date replicas Queuing Service sends an AppAck message to the QueuePro ducer Enqueued Enqueued Queuing Service decides which QueueConsumer should get the sample If SharedReaderQueue replication is enabled the selected QueueConsumer has been communicated to the replicas and optionally confirmed by a quorum of up to date repli cas Assigned Selecting a QueueConsumer for a Sample Table 2 1 2 10 2 1
132. ue from the command line The variable value can be provided using the var command line option see Queuing Service runs as a separate application The script to run the executable is in lt NDDSHOME gt bin There are four ways to start Oueuing Service Section 2 Ifthe value is not found the parser will try to get it from the OS environment variables 3 Ifthe value still cannot be found the parsing process will fail 3 5 Enabling RTI Distributed Logger in Queuing Service Queuing Service provides integrated support for RTI Distributed Logger When you enable Distrib uted Logger Queuing Service will publish its log messages to Connext DDS You can use RTI Monitor to visualize the log message data Since the data is provided in a topic you can also use RTI DDS Spy rtiddsspy or even write your own visualization tool To enable Distributed Logger modify the Queuing Service XML configuration file In the lt admin istration gt section add the lt distributed_logger gt tag as seen here lt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation rti_ queuing service xsd gt lt queuing service name QueuingService_1 gt lt administration gt lt distributed logger gt lt enabled gt true lt enabled gt lt distributed logger gt lt administration gt lt gueuing service gt lt dds gt There are more configuration tags that you can use to control Distributed Logger s behavi
133. ue_instances gt under lt replication_settings gt see SharedReaderQueue Replication Configuration Section 7 1 3 After the sample is moved to the ENQUEUE state the master and slaves send an AppAck mes sage to the QueueProducer indicating that the sample has been successfully enqueued The response data of the AppAck message for successfully enqueued samples will be a single byte set to 1 Positive AppAck messages are global AppAck messages Therefore when monitoring AppAck messages the QueueProducer can assume that a sample has been successfully enqueued as soon as it receives a positive acknowledgment from any of the replicas master or slaves 7 3 SharedReaderOueue Replication 7 1 1 3 7 1 1 4 If there is no a quorum of up to date replicas that are able to enqueue the sample the replicas will send an AppAck message to the QueueProducer s Data Writer where the response is set to 0 Negative AppAck messages are local messages In order to consider a message as not enqueued a QueueProducer must receive a negative AppAck from all replicas To make this decision easier you can use the DataWriter s is sample app acknowledged operation it returns TRUE when a sample has been application acknowledged negatively or positively by all replicas that were alive when the sample was published If the QueueProducer has not received a positive AppAck message for a sample and the is sample app acknowledged returns TRUE the sample ca
134. ueue and returns a response to the requester application Realizing the request reply communication model requires creating a new SharedReaderQueue that will be used to send responses from the replier application to the requester application see Figure 2 5 Figure 2 5 Request Reply Communication Model Requester Application 1 Queuing Service SARTO Shared Subscriber Producer Request Consumer Response Replier Application 1 Consumer Request Req 1 Requester Application 2 Res 2 Producer Reguest Producer Response Consumer Response uil 2 11 1 Requester Identification In a request reply pattern requests must uniquely identify the associated QueueProducer so that each reply sample can be unambiguously delivered to the requester application that sent the associated request To identify a QueueProducer you can use the source GUID 2 13 Sending a Reply from OueueConsumer to OueueProducer The source guid consists of a GUID it can be set per sample using the source guid field in the WriteParams t parameter provided to the OueueProducer s DataWriter write w params oper ation If you do not want to set the source GUID of a sample the OueueProducer s DataWriter will assign it automatically to be equal to the DataWriter s virtual GUID In general you should always assign the source GUID when sending reguests Otherwis
135. uid SGUID_ related original publication virtual guid GUID related sample identity writer guid GUID related original publication virtual seguence number SN related sample identity seguence number SN e The replier application can extract the source GUID of a request from the field related source guid of the Samplelnfo associated with the reguest sample see Figure 2 6 Once the replier application extracts the request sample identity and source GUID from the request Samplelnfo it must attach them to the reply sample as follows LJ The sample identity will be set using the field related sample identity in the WriteParams t parameter provided to the DataWriter s write w params operation J The source GUID will be set using the field related source guid in the WriteParams t parameter provided to the DataWriter s write w params operation 2 14 Dead Letter Oueues 2 11 3 2 11 4 2 11 5 2 12 When the reguester application receives the reply it can associate the reply with the correspond ing request by inspecting the related original publication virtual guid and related original publication virtual seguence number fields in the Samplelnfo associated with the reply sample see Figure 2 6 Sending the Reply Sample to the Associated Reguester To guarantee that a reply sample is only distributed to right Reguester the DataReader in the Reguester must use a ContentFilteredTopic on the related source gui
136. very has been received from the QueueCon sumer In addition if SharedReaderQueue replication is enabled the delivery of the sample must have been communicated to the replicas See Chapter 7 High Availability 2 9 Sample Lifecycle In Oueuing Service Table 2 1 IJ Rejected The sample has been delivered to the selected QueueConsumer and the appli cation level acknowledgment from the QueueConsumer has been received with an indi cation that the message has been rejected LJ Timed out The sample has been delivered to the selected QueueConsumer and it has not been application level acknowledged from the QueueConsumer for a configurable maximum time set using the tag lt response_timeout gt under lt queue_qos gt lt redeliv ery gt see Table 3 15 Queue QoS Tags l Expired Indicates a sample that has exceeded a configurable maximum time to be held by Queuing Service The sample lifespan can be configured per SharedReaderQueue or per QueueProducer e To configure the sample lifespan per SharedReaderQueue use the lt lifespan gt tag under lt gueue gos gt see Table 3 15 Queue QoS Tags To configure the sample lifespan per QueueProducer set the Lifespan QoS policy for the QueueProducer s DataWriter This way all the samples sent by that Queue Producer will have a lifespan equal to the writer gos lifespan duration The lifes pan per QueueProducer when finite takes precedence over the lifespan per SharedReaderQue
137. with remoteAd ministrationDomainld to obtain the initial configuration from other running instances Set remoteAdministrationDomainld to the administration domain ID that will be used to send remote commands If you do not use cfgRemote the service will not get the ini tial configuration remotely and it will start from the provided file When replication is enabled remote administration commands that change the service configu ration such as adding or removing a SharedReaderQueue should be sent to all the Queuing Ser vice instances by using lt CommonPrefix gt as the target queuing service field service name in CommandReguest see Chapter 5 Administering Oueuing Service from a Remote Location In the above example the field service name would be set to Cluster 1 The application sending the command will receive a response from each one of the members in the cluster confirming the successful execution of the command Notice that an application could still send a command to multiple Queuing Service instances without enabling replication The difference in this case is that the final configuration may not be consistent across instances if multiple applications send remote commands at the same time By enabling replication using the tag lt configuration replication gt we guarantee configuration consistency across all the instances in the cluster SharedReaderAueue for Configuration Replication To enable configuration replicatio
138. xsd gt lt types gt lt struct name Foo gt lt member type string stringMaxLength 255 name message gt lt struct gt lt struct name Bar gt lt member type string stringMaxLength 255 name message gt lt struct gt lt types gt lt queuing service name QueuingService_1 gt lt domain participant name DomainParticipant_1 gt lt domain id gt 57 lt domain id gt lt shared subscriber name SharedSubscriber 1 gt lt session_settings gt lt session name Session_1 gt lt session_settings gt lt dead letter shared reader queue name DeadLetter 1 session Session 1 gt lt topic name gt DeadLetter lt topic name gt lt dead letter shared reader gueue gt lt shared reader gueue session Session 1 dead letter gueue DeadLetter 1 gt lt topic name gt HelloWorld lt topic name gt lt type name gt Foo lt type name gt lt reply type gt Bar lt reply type gt lt shared reader gueue gt lt shared subscriber gt lt domain participant gt lt gueuing service gt lt dds gt When types are defined in XML Queuing Service is registering them with the underlying DDS DomainParticipant using as the registration name the fully qualified name of the type under the lt type gt tag If you refer to types that are not defined in the configuration file Queuing Service has to discover the type representation e g a typeobject A SharedReaderQueue cannot be instantiated with
139. y XML attribute session in lt shared reader gueue gt and lt dead letter shared reader gueue gt respectively using the Table 3 13 Session Tags Tags within lt session gt Description Number of Tags Allowed lt degueue period gt Configures the period at which Queuing Service retries sending samples that have not been delivered to a OueueConsumer upon reception This can happen when the available QueueConsumers cannot accept the samples or if there are no QueueConsumers in the system for a SharedRead erQueue Example lt session gt lt thread gt lt dequeue period gt lt sec gt 1 lt sec gt lt nanosec gt 0 lt nanosec gt lt dequeue period lt thread gt lt session gt Default 10 msec 0or1 lt monitoring gt Enables and configures remote Pub Sub monitoring for the SharedReader Oueue See Configuring Monitoring Section 3 3 4 and Chapter 6 Publish Subscribe Monitoring of Oueuing Service from a Remote Location 0or1 lt replication gt Enables SharedReaderOueue replication See Chapter 7 High Availability 0or1 lt statistics gt Configures the statistic gathering process for publish subscribe or reguest reply monitoring of the SharedReaderOueue See Configuring Monitoring Section 3 3 4 0or1 lt thread gt Sets the mask priority and stack size of the threads associated with this ses sion Example lt session gt lt thread gt

User`s Manual - Community RTI Connext Users

Contents

Download Pdf Manuals

Related Search

Related Contents