.. highlight:: c

Thread Safety
=============

All public APIs have a note about thread-safety included in the API
reference manuals. It is important that an application does not violate
thread-safety guidelines. |rti_me| creates one critical section per 
*DomainParticipant* to protect resources used by the *DomainParticipant*.

.. note::

   Although |me| may create multiple mutexes,
   these are used to protect resources in the OSAPI layer, and are thus not
   relevant when using the public DDS APIs.


Calling DDS APIs from listeners and callbacks
.............................................

When DDS is executing in a listener, it holds a critical section. Thus it is
important to return as quickly as possible to avoid stalling network I/O.

There are no deadlock scenarios when a listener calls |me| DDS APIs
from the **same** *DomainParticipant* (and contained entities) that the listener 
was called from, as shown in the diagram below:

.. image:: ../images/ThreadSafety-OK.png
    :align: center
    :width: 400

.. warning::
    It is **not** safe to call DDS APIs from a **different** *DomainParticipant*
    than the one listener was called from, as shown in the diagram below. This may 
    result in a deadlock situation.

    .. image:: ../images/ThreadSafety-NOK.png
       :align: center
       :width: 800

.. warning::
    There are no checks on whether or not an API call will cause problems, such 
    as deleting a participant when processing data in :link_connextmicro_dds_api_c_up_one:`on_data_available <structDDS__DataReaderListener.html>` 
    from a reader within the same participant.

Calling DDS APIs from a type-plugin
...................................

A user type-plugin that is registered with the *DomainParticipant* is
subject to the following rules:

- The key kind is constant.
- The plugin is constant for a given DDS entity (*Topic*, *DataWriter*,
  or *DataReader*).
- The plugin data must be protected if thread safety is a concern, as it
  is user data and not protected by |me|.

.. note::
   A type-plugin generated from an IDL file with the *rtiddsgen*
   IDL compiler included with |me| will satisfy these rules.