.. _Reliability: ../../../api_c/html/group__DDSReliabilityQosModule.html
.. _Durability: ../../../api_c/html/group__DurabilityQosPolicyModule.html

.. highlight:: c

INTRA Transport
---------------

The builtin intra participant transport (INTRA) is a transport that 
bypasses RTPS and reduces the number of data-copies from three to one for
data published by a *DataWriter* to a *DataReader* within the same 
participant. When a sample is published, it is copied directly to the data 
reader’s cache (if there is space). This transport is used for communication 
between *DataReaders* and *DataWriters* created within the same participant 
by default.

Please refer to :ref:`intra_threads` for important details regarding application 
constraints when using this transport.

Registering the INTRA Transport
...............................
 
The builtin INTRA transport is a |rti_me| component that is automatically 
registered when the :link_connextmicro_dds_api_c_up_two:`DomainParticipantFactory_get_instance() <group__DDSDomainParticipantFactoryModule.html>`
method is called. By default, data published by a *DataWriter* is sent to all 
*DataReaders* within the same participant using the INTRA transport. 

In order to prevent the INTRA transport from being used it is necessary
to remove it as a transport and a user-data transport. The following 
code shows how to only use the builtin UDP transport for user-data.

::
 
    struct DDS_DomainParticipantQos dp_qos =
                                DDS_DomainParticipantQos_INITIALIZER;
    
    REDA_StringSeq_set_maximum(&dp_qos.transports.enabled_transports,1);
    REDA_StringSeq_set_length(&dp_qos.transports.enabled_transports,1);
    *REDA_StringSeq_get_reference(&dp_qos.transports.enabled_transports,0) =
                                        REDA_String_dup(NETIO_DEFAULT_UDP_NAME);

    /* Use only unicast for user-data traffic. */
    REDA_StringSeq_set_maximum(&dp_qos.user_traffic.enabled_transports,1);
    REDA_StringSeq_set_length(&dp_qos.user_traffic.enabled_transports,1);
    *REDA_StringSeq_get_reference(&dp_qos.user_traffic.enabled_transports,0) =
                                        REDA_String_dup("_udp://");

Note that the INTRA transport is never used for discovery traffic internally.
It is not possible to disable matching of *DataReaders* and *DataWriters* within 
the same participant.

Reliability and Durability
..........................

Because a sample sent over INTRA bypasses the RTPS reliability and DDS durability 
queue, the Reliability_ and Durability_ Qos policies are *not* supported by the INTRA 
transport. However, by creating all the *DataReaders* before the *DataWriters*
durability is not required.

.. _intra_threads:

Threading Model
...............

The INTRA transport does not create any threads. Instead, a *DataReader* 
receives data over the INTRA transport in the context of the *DataWriter*’s 
*send thread*.

This model has two *important limitations*: 

- Because a *DataReader*’s :link_connextmicro_dds_api_c_up_two:`on_data_available() <structDDS__DataReaderListener.html>`
- listener is called in the context of the *DataWriter*'s send thread, a *DataReader* may potentially process 
  data at a different priority than intended (the *DataWriter*'s). While it is 
  generally not recommended to process data in a *DataReader*'s 
  :link_connextmicro_dds_api_c_up_two:`on_data_available() <structDDS__DataReaderListener.html>`
  listener, it is particularly important *to not do so*
  when using the INTRA transport. Instead, use a DDS WaitSet or a similar 
  construct to wake up a separate thread to process data.

- Because a *DataReader*’s :link_connextmicro_dds_api_c_up_two:`on_data_available() <structDDS__DataReaderListener.html>`
- listener is called in the context of the *DataWriter*'s send thread, any method called in the 
  :link_connextmicro_dds_api_c_up_two:`on_data_available() <structDDS__DataReaderListener.html>`
  listener is done in the context of the *DataWriter*'s
  stack. Calling a *DataWriter* **write()** in the callback could result in an infinite 
  call stack.  Thus, it is recommended *not* to call in this listener 
  any |me| APIs that write data.