4.1. Initializing the Connext Micro Library

Connext Micro has been designed to integrate with a wide range of operating systems, network stacks, and CPUs. For this reason, Connext Micro places few restrictions on how it is integrated. The memory management API defined by Connext Micro may be implemented using standard C libray APIs such as malloc() and free(), or something hardware specific relying on memory being allocated from a specific memory region.

In order to allow a degree of flexibility, integrations may be configurable at run-time. This configuration may require validation before it is safe to make specific calls, such as allocating memory.

In order to guarantee consistency accross all integrations for when it is safe to call APIs, Connext Micro requires that its library is initialized with DDS_DomainParticipantFactory_get_instance before any public APIs are called, unless an API is documented to be safe to call before DDS_DomainParticipantFactory_get_instance. DDS_DomainParticipantFactory_get_instance initializes an integration, providing an opportunity for integrations to validate its configuration.

Note

This restriction is not limited to DDS APIs, but extends to all public APIs, such as sequence APIs, type-support APIs, string APIs, and component APIs.

Connext Micro is initialized with a successful call to DDS_DomainParticipantFactory_get_instance. On success, DDS_DomainParticipantFactory_get_instance returns a reference to a DDS_DomainParticipantFactory; on failure, ‘nil’ is returned:

DDS_DomainParticipantFactory *factory = NULL;

factory = DDS_DomainParticipantFactory_get_instance();

if (factory == NULL)
{
    /* something failed, exit */
    exit(-1);
}

/* Safe to call other public APIs */

After a successful call to DDS_DomainParticipantFactory_get_instance, public APIs are safe to call as documented. APIs that must not be called before DDS_DomainParticipantFactory_get_instance have the following additional description:

API Restriction:
This function must only be called after DDS_DomainParticipantFactory_get_instance.

Warning

DDS_DomainParticipantFactory_get_instance is not guarenteed to be thread-safe.

4.1.1. rtiddsgen

rtiddsgen is the type support compiler included with Connext Micro. rtiddsgen generates code to send and receive data types across the network, as well as to allocate memory to store data types in memory. These memory allocations use the memory management APIs defined by Connext Micro.

Because each integration determines how these APIs are implemented, it is important that TypeSupport APIs are not called until Connext Micro has been initialized. APIs such as FooTypeSupport_create_data and FooTypeSupport_delete_data are not safe to call until after a successful call to DDS_DomainParticipantFactory_get_instance:

DDS_DomainParticipantFactory *factory = NULL;
Foo *sample = NULL;

/* NOT ALLOWED */
sample = FooTypeSupport_create_data();

factory = DDS_DomainParticipantFactory_get_instance();

if (factory == NULL)
{
    /* something failed, exit */
    exit(-1);
}

/* ALLOWED */
sample = FooTypeSupport_create_data();
if (sample == NULL)
{
    /* something failed, exit */
    exit(-1);
}

/* Calls other public APIs */

4.1.2. The Connext Micro System API

The Connext Micro System API enables applications to configure the behavior of Connext Micro at runtime. Which configuration options are available depends on the specific integration.

However, because the Connext Micro system must be configured before Connext Micro is initialized, it is safe to call public System APIs before DDS_DomainParticipantFactory_get_instance, such as OSAPI_System_get_property and OSAPI_System_set_property:

struct OSAPI_SystemProperty sys_property = OSAPI_SystemProperty_INITIALIZER;
DDS_DomainParticipantFactory *factory = NULL;

if (!OSAPI_System_get_property(&sys_property))
{
    /* error */
    return;
}

/* Set sys_property */

if (!OSAPI_System_set_property(&sys_property))
{
    /* error */
    return;
}

factory = DDS_DomainParticipantFactory_get_instance();
if (factory == NULL)
{
    /* error */
    return;
}

4.1.3. Component Registration

Connext Micro consists of core APIs and additional components that extend its functionality. Connext Micro includes two components which must always be registered with Connext Micro before any DDS entities can be created: the writer and reader history caches. The following code sample demonstrates how to register these:

#include "wh_sm/wh_sm_history.h"
#include "rh_sm/rh_sm_history.h"


DDS_DomainParticipantFactory *factory = NULL;
RT_Registry_T *registry = NULL;

factory = DDS_DomainParticipantFactory_get_instance();

if (factory == NULL)
{
    /* something failed, exit */
    exit(-1);
}

registry = DDS_DomainParticipantFactory_get_registry(factory);

if (registry == NULL)
{
    /* something failed, exit */
    exit(-1);
}

if (!RT_Registry_register(registry, DDSHST_WRITER_DEFAULT_HISTORY_NAME,
                          WHSM_HistoryFactory_get_interface(), NULL, NULL))
{
    /* something failed, exit */
    exit(-1);
}

if (!RT_Registry_register(registry, DDSHST_READER_DEFAULT_HISTORY_NAME,
                          RHSM_HistoryFactory_get_interface(), NULL, NULL))
{
    /* something failed, exit */
    exit(-1);
}

Connext Micro includes other components, such as Discovery plugins and the UDP Transport. These are documented in other sections.