Entity examples

How to use Rti.Dds.Core.Entity types: set QoS, monitor status changes, and more.

How to use Rti.Dds.Core.Entity types: set QoS, monitor status changes, and more.

The following code snippets show common operations to all Rti.Dds.Core.Entity types, including:

• Rti.Dds.Domain.DomainParticipant
• Rti.Dds.Topics.Topic
• Rti.Dds.Publication.Publisher
• Rti.Dds.Subscription.Subscriber
• Rti.Dds.Publication.DataWriter
• Rti.Dds.Subscription.DataReader

Sections:

• Configure an Entity's QoS
• Monitor an Entity's status changes
• Disposing an Entity
• Entity Discovery

Configure an Entity's QoS

Example: set the default DomainParticipantQos for new DomainParticipants

    var factory = Rti.Dds.Domain.DomainParticipantFactory.Instance;
 
    // This assignment is doing several things:
    // 1) Get the current default DomainParticipantQos
    // 2) Create a new DefaultParticipantQos object by modifying two
    //    policies (Property and Database)
    // 3) Use this object to set a new default DomainParticipantQos
    factory.DefaultParticipantQos = factory.DefaultParticipantQos
        .WithProperty(policy => policy.Add("CompanyName", "Acme, Inc."))
        .WithDatabase(policy => policy.ShutdownCleanupPeriod = Duration.FromMilliseconds(100));
 
    // This DomainParticipant uses the new DomainParticipantQos we just set
    using Rti.Dds.Domain.DomainParticipant participant =
        factory.CreateParticipant(domainId: 0);
 
    Debug.Assert(
        participant.Qos.Property.Value["CompanyName"].Value == "Acme, Inc.");

Example: set the default DataReaderQos for new DataReaders created from a Subscriber

    Rti.Dds.Subscription.Subscriber subscriber =
        participant.CreateSubscriber();
 
    // Update the default QoS as we did in the previous example
    subscriber.DefaultDataReaderQos = subscriber.DefaultDataReaderQos
        .WithReliability(policy => policy.Kind = ReliabilityKind.Reliable)
        .WithDurability(policy => policy.Kind = DurabilityKind.TransientLocal)
        .WithHistory(policy =>
        {
            policy.Kind = HistoryKind.KeepLast;
            policy.Depth = 20;
        });
 
    // The new QoS we just set applies to all new readers created by this
    // subscriber
    var reader = subscriber.CreateDataReader(topic);
 
    Debug.Assert(
        reader.Qos.Durability.Kind == DurabilityKind.TransientLocal);

Example: create a DataReader with specific QoS

    Rti.Dds.Subscription.Subscriber subscriber =
        participant.CreateSubscriber();
 
    // Create a DataReaderQos as a copy of subscriber.DefaultDataReaderQos
    // with a few changes.
    //
    // Each "With<Policy>" call returns a new DataReaderQos
    // object with the same values as before, except the for the new policy
    // that is being set. At the end, readerQos is a new object containing
    // the values we set for Reliability, Durability, ResourceLimits and Property.
    // The rest of QoS policies retain the value in subscriber.DefaultDataReaderQos.
    DataReaderQos readerQos = subscriber.DefaultDataReaderQos
        .WithReliability(policy => policy.Kind = ReliabilityKind.Reliable)
        .WithDurability(policy => policy.Kind = DurabilityKind.TransientLocal)
        .WithResourceLimits(policy =>
        {
            policy.InitialSamples = 10;
            policy.MaxSamples = 40;
            policy.MaxSamplesPerInstance = 10;
        })
        .WithProperty(policy =>
        {
            policy.Add("Company", "Acme, Inc.");
            policy.Add("Group", "GroupA");
        });
 
    // Create the DataReader with the QoS we just defined
    var reader = subscriber.CreateDataReader(topic, readerQos);
 
    Debug.Assert(
        reader.Qos.Property.Value["Company"].Value == "Acme, Inc.");

Example: modify a mutable DataReader QoS policy after creation

    Rti.Dds.Subscription.DataReader<Example.MyType> reader =
        subscriber.CreateDataReader(topic);
 
    reader.Qos = reader.Qos
        .WithProperty(property => property["Group"] = "GroupB");
 
    Debug.Assert(reader.Qos.Property.Value["Group"].Value == "GroupB");

Example: create a DataReader with a built-in QoS profile

 
    // The built-in profiles are available in any QosProvider, including
    // the default one. The default QosProvider also automatically loads
    // the profiles in the file USER_QOS_PROFILES.xml in the working
    // directory if it exists, and a few other locations.
    var strictReliableQos = QosProvider.Default.GetDataReaderQos(
        "BuiltinQosLib::Generic.StrictReliable");
 
    // You can optionally modify additional QoS policies:
    strictReliableQos = strictReliableQos.WithSubscriptionName("MyReader");
 
    // Create the DataReader with the QoS we just defined
    var reader = subscriber.CreateDataReader(topic, strictReliableQos);
 

Example: create a DataReader with a custom QoS profile

    // To load a custom XML file with QoS profiles, create a QosProvider
    var qosProvider = new QosProvider("MyProfiles.xml");
 
    var subscriberQos = qosProvider.GetSubscriberQos("MyLibrary::MyProfile");
    var subscriber = participant.CreateSubscriber(subscriberQos);
 
    // If you don't specify a "Library::Profile" string, the QosProvider will
    // look for one with the attribute is_default_qos="true"
    var readerQos = qosProvider.GetDataReaderQos();
    var reader = subscriber.CreateDataReader(topic, readerQos);

These examples from the rticonnextdds-examples GitHub repository show other uses cases related to configuring QoS:

• Printing QoS
• Group Coherent Presentation,
• Custom Flow Controller,
• Multichannel

Monitor an Entity's status changes

Example: set up events to handle status updates for an Entity

 
    // The event handlers for status updates can be set at the moment of
    // creation to avoid missing any status update.
    var reader = subscriber.CreateDataReader(
        topic,
        preEnableAction: reader =>
        {
            // In this function, reader has not been enabled yet
            reader.SubscriptionMatched += (_, status)
                => Console.WriteLine($"Total matched publications = {status.TotalCount}");
            reader.LivelinessChanged += MyLivelinessChangedHandler;
        });
 
    // Event handlers can be removed or added after creation:
    reader.LivelinessChanged -= MyLivelinessChangedHandler;
    reader.RequestedIncompatibleQos += (_, status) =>
    {
        var policy = status.LastPolicy.Name;
        Console.WriteLine($"Incompatible QoS: {policy}");
    };
 
    // To remove multiple events handlers:
    reader.ResetEvents(StatusMask.SubscriptionMatched | StatusMask.DataAvailable);
 
    // To remove all event handlers:
    reader.ResetEvents(StatusMask.All);
 

Example: lookup the current status of an Entity

 
    var samplesLost = reader.SampleLostStatus.TotalCount;
    var incompatiblePublications = reader.RequestedIncompatibleQosStatus.TotalCount;
    Console.WriteLine($"Reader has lost {samplesLost} samples and found {incompatiblePublications} incompatible publications");
 

The Instance Statistics example from the rticonnextdds-examples GitHub repository shows how to look up statistics related to a DataWriter and a DataReader.

Disposing an Entity

An Entity can be deleted by explicitly disposing it or by disposing its factory. In many applications, it is only necessary to dispose the DomainParticipants.

To dispose an entity call its Dispose() method or scope it with the using keyword.

See, for example, Writing data and instances.

Entity Discovery

Information about discovered DomainParticipants, DataReaders, and DataWriters can be accessed using the built-in discovery readers in Rti.Dds.Domain.DomainParticipant.BuiltinSubscriber. See the Builtin Topics example from the rticonnextdds-examples GitHub repository.

You can also look up information about the publications/subscriptions that match with a local subscription/publication. See Looking up matched publications.