.. _ros-keyed-topics:

Keyed Topics
============
In ROS 2, the concept of `keyed types or instances <https://community.rti.com/static/documentation/connext-dds/7.3.0/doc/manuals/connext_dds_professional/getting_started_guide/cpp11/intro_keys_instances.html>`__
doesn't exist. Messages in ROS 2 do not support having a member that is a key. 

However, the ROS 2 parser transforms the ROS 2 message definition into IDL
before code generation. Then this IDL code is parsed by an OMG-compliant parser,
which generates code for different languages. Since the IDL parser is
OMG-compliant, it also supports many features from IDL that are not used inside
the ROS 2 design. One of those is the ability to mark a field as ``@key``.

The |CONNEXT| RMW implements the necessary functionality to take advantage of
that information and allow the publication/subscription of keyed messages.
This is implemented with |CONNEXT| instances under the hood. However, there is
no available API in the RMW to manage those instances.

For example, instance creation is done automatically by the |CONNEXT| RMW
when a keyed sample is sent to the subscription. However, functionality like
disposing instances or unregistering instances is not available.
Making them available would require consensus in the ROS 2 community
to make them available through the RMW API.

Since the ROS 2 message definition format doesn't support declaring keys,
you must slightly modify the code generation process to inject this
information. To do this:

#. Transform the ``.msg/.srv`` files into ``.idl`` files.
#. Manually modify the corresponding field into a key by
   adding the ``@key`` notation. 
   
The ROS IDL parser will take care of
parsing the modified ``.idl`` file and generating the necessary code.

This workaround goes away once the ROS 2 message format
definition allows declaring a field as a key.