Register the Instance and Use the InstanceHandle When Writing for Better Performance

When you write keyed data, the RTI Connext DDS has to send the unique identifier of each instance along with the data.  This unique identifier is sixteen bytes of serialized data, based on the values of the key fields in your data.  Depending on how many key fields you have, and how complex they are, this unique identifier may be a simple memcopy into the key serialization stream, or it may require that the middleware performs an md5 hash of the values of the key fields before copying the result into the key serialization stream.

When writing keyed data, you have the option to preregister an instance handle, and to pass it into the write() call, or to pass in an instance handle set to DDS_INSTANCE_HANDLE_NIL.  If you pass in DDS_INSTANCE_HANDLE_NIL, the middleware must serialize the key fields into the 16 byte hash.  If you pre-register your instance, you are returned an instance handle.  When you pass this instance handle into the write() call, it allows the middleware to look up the serialized key, rather than re-serializing that key.  

Note that this performance difference will be greater if you have a complex set of fields that comprise your key.  If your key is simple, it may be just as fast to re-serialize it as to look it up.

Caution: If you preregister your instances, you must ensure that the instance handle you pass into the write() call actually matches the value of the key fields of the data you are writing.  For performance reasons, RTI Connext DDS does not check that the instance handle matches the key fields of the data being written.

An example of pre-registering the instance handle:

handle = trackWriter->register_instance(track);
_instanceMap[&track] = handle;

// ...

// Look up the pre-registered instance
handle = _instanceMap[&track];
DDS_ReturnCode_t retcode = _trackWriter->write(track, handle);