Skip to content

Extend @key annotation documentation #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Mario-DL wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Extend @key annotation documentation #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 42 additions & 1 deletion articles/115_idl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,48 @@ If a cell is blank then the default mapping is used.

#### 8.3.2.1 @key Annotation

While the key annotation doesn't affect the generated ROS data types directly it is being passed through to the (DDS) vendor specific code generators.
[ROS 2 nodes](ros_on_dds.html) exchange information of a certain real world object by means of topics.
Every message in a topic is known as *data sample* and represents an update to the status of the object.

Topic instances are a way of multiplexing the transmission of updates of several objects of the same logical kind over the same resource, i.e. the topic.
In a *keyed topic*, every message is associated with a topic instance and each topic instance is identified by a unique key.
In this sense, keys can be thought as the *primary key* of a database.
This key allows nodes to update different states of the same kind.
In consequence, all data samples sharing the same key value refer to the same object.

The key is represented using a 16 bytes sequence called key-hash and the `@key` annotation allows indicating that a data member is part of the key, which can have zero or more key fields and can be applied to structure fields of various types.
The following example shows how to define a keyed message using the IDL format:

```
# KeyedMsgName.idl
module package_name {
module msg {
struct KeyedMsgName {
@key long member1;
string member2;
};
};
};
```

<div class="alert alert-info" markdown="1">
Currently, the message interface format that supports the `@key` annotation is `.idl`.
Hence, `.msg` and `.srv` do not support the `@key` annotation yet.
Please refer to [Conversion to IDL](legacy_interface_definition.html) for further information on the equivalence and conversion among them.
</div>

The general-purpose idl types including primitive types, sequences, strings and structs can be annotated as keys.
Following are some examples:

| Type | Key Members |
|----------------------------------------|------------------------------|
| struct NoKey <br/>{ boolean member1;<br/> long member2;<br/> long member3; } | None |
| struct SimpleKey <br/>{ @key long member1; <br/>long member2; } | member1 |
| struct ArrayKey <br/>{ @key long member1[3]; } | member1[0] <br> member1[1] <br> member1[2] |
| struct StringKey <br/>{ @key string member1; <br> long member2} | member1 |
| struct NestedNoKey <br/>{ SimpleKey member1;<br/> long member2; } | |
| struct NestedKey <br/>{ @key SimpleKey member1;<br/> long member2; } | member1.member1 |
| struct NestedKey2 <br/>{ @key NoKey member1;<br/> long member2; } | member1.member1 <br> member1.member2 <br> member1.member3 |

#### 8.3.3.1 @default Annotation

Expand Down