1.1.2. Instance

class eprosima::is::core::Instance

Base class for creating an Integration Service instance. It can be called directly, or under the wrapping methods run_instance.

Public Functions

Instance(int argc, char *argv[])

Creates an Integration Service instance which receives the arguments fed by the user from the command line.

Parameters

  • [in] argc: Number of arguments given.

  • [in] argv: String representation list of arguments provided, to be parsed before launching the instance.

Instance(const YAML::Node &config_node, const std::vector<std::string> &is_prefixes, const MiddlewarePrefixPathMap &middleware_prefixes)

Creates an Integration Service instance explicitly indicating the configuration of the Integration Service core and of the dedicated middleware SystemHandle plugins, and setting their relevant properties.

Parameters

  • [in] config_node: The YAML configuration file, structured as defined in the is::core::internal::Config::parse() method documentation, that should be provided to Integration Service to successfully start a communication between two or more applications using different communication protocols.

  • [in] is_prefixes: Global prefix paths for Integration Service to search for configuration files or mix files.

    These act as a complement to the already existing environment variables created during compilation/installation steps by CMake.

  • [in] middleware_prefixes: Prefix paths specific to a certain middleware. Used when loading a middleware’s plugin, that is, its SystemHandle implementation.

Instance(const std::string &config_file_path, const std::vector<std::string> &is_prefixes, const MiddlewarePrefixPathMap &middleware_prefixes)

Creates an Integration Service instance explicitly indicating the configuration of the Integration Service core and of the dedicated middleware SystemHandle plugins, and setting their relevant properties.

Parameters

  • [in] config_file_path: The YAML configuration file, structured as defined in the is::core::internal::Config::parse() method documentation, that should be provided to Integration Service to successfully start a communication between two or more applications using different communication protocols.

  • [in] is_prefixes: Global prefix paths for Integration Service to search for configuration files or mix files.

    These act as a complement to the already existing environment variables created during compilation/installation steps by CMake.

  • [in] middleware_prefixes: Prefix paths specific to a certain middleware. Used when loading a middleware’s plugin, that is, its SystemHandle implementation.

~Instance()

Destructor.

InstanceHandle run()

Runs the Integration Service instance in its own thread.

The handle allows to wait on that thread or instruct it to quit.

The handle uses RAII, so the instance will stop running automatically if the InstanceHandle dies.

If run() is called again while another instance handle is still alive and running, the new instance handle will still refer to the previously started and still running instance. Calling quit() on any of the handles will make them all quit. The automatic RAII shutdown of the instance will become effective once all handles have died.

If the existing handles are still alive but no longer running, they will become detached from this instance, and calling run() will initiate a new set of instance handles.

In most cases, simply calling one of the run_instance() functions and not worrying about how InstanceHandle entities might interact is more than enough.

Return

An InstanceHandle to manage the running Integration Service instance.

using eprosima::is::core::MiddlewarePrefixPathMap = std::unordered_map<std::string, std::vector<std::string>>

MiddlewarePrefixPathMap contains a map of the prefixes that are available for each middleware. These prefixes are used to look for the dynamic libraries of either the SystemHandle plugin or the MiddlewareInterfaceExtension files and, once they are located, to load them.

See

Search

1.1.3. InstanceHandle

class eprosima::is::core::InstanceHandle

This is the class responsible of handling an Integration Service instance.

It allows to perform several actions on the Integration Service instance, such as asking whether it is running or not or handling the threads that are launched each time a SystemHandle is launched from the core.

It also allows to quit the instance in a safe way, waiting for the pending jobs to finish.

Public Functions

InstanceHandle(const InstanceHandle &other)

Copy constructor.

Parameters

InstanceHandle(InstanceHandle &&other)

Move constructor.

Parameters

~InstanceHandle()

Destructor.

The destructor will call quit() and then wait(), because the Integration Service instance cannot run without the handle active.

bool running() const

It allows to check if the instance is still running.

Return

true if the Integration Service instance is still running, false otherwise.

operator bool() const

bool() operator overload. It performs an implicit cast to running().

Return

true if the Integration Service instance is still running, false otherwise.

int wait()

Waits for the instance to stop running.

The instance may be stopped by calling quit() or by sending SIGINT (ctrl+C from the terminal).

Return

The return code for the execution process of this instance.

InstanceHandle &wait_for(const std::chrono::nanoseconds &max_time)

Waits for the instance to stop running, or for the max time to be reached.

Return

A reference to this instance handle, so that it can be chained with quit() or wait().

Parameters

  • [in] max_time: Time, in nanoseconds, to wait for the instance to finish running.

InstanceHandle &quit()

Instructs the node handle to quit (this will not occur instantly).

After this, it calls wait() in order to wait until the instance has finished running, and retrieves the return code.

Return

A reference to this instance handle so that it can be chained with wait_for() or wait().

const TypeRegistry *type_registry(const std::string &middleware_name)

Requests the TypeRegitry for a given middleware.

Return

A pointer to the TypeRegistry, or nullptr if the middleware does not exist.

Parameters

  • [in] middleware_name: The middleware whose TypeRegistry is to be retrieved.

core::InstanceHandle eprosima::is::run_instance(int argc, char *argv[])

Creates an Integration Service instance and runs it in its own thread. This is a wrapper for the core::Instance constructor and for the core::Instance::run() method.

Return

An InstanceHandle to manage the running Integration Service instance.

Parameters

  • [in] argc: Number of given arguments.

  • [in] argv: String representation list of the provided arguments, to be parsed before launching the instance.

core::InstanceHandle eprosima::is::run_instance(const std::string &config_file_path, const std::vector<std::string> &is_prefixes = {}, const core::MiddlewarePrefixPathMap &middleware_prefixes = {})

Creates an Integration Service instance and runs it in its own thread. This is a wrapper for the core::Instance constructor and the run() method.

Return

An InstanceHandle to manage the running Integration Service instance.

Parameters

  • [in] config_file_path: The YAML configuration file, structured as defined in the is::core::internal::Config::parse() method documentation, that should be provided to Integration Service to successfully start a communication between two or more applications using different communication protocols.

  • [in] is_prefixes: Global prefix paths for Integration Service to search for configuration files or mix files.

    These act as a complement to the already existing environment variables created during compilation/installation steps by CMake.

  • [in] middleware_prefixes: Prefix paths specific to a certain middleware. Used when loading a middleware’s plugin, that is, its SystemHandle implementation.

core::InstanceHandle eprosima::is::run_instance(const YAML::Node &config_node, const std::vector<std::string> &is_prefixes = {}, const core::MiddlewarePrefixPathMap &middleware_prefixes = {})

Creates an Integration Service instance and runs it in its own thread. This is a wrapper for the core::Instance constructor and the run() method.

Return

An InstanceHandle to manage the running Integration Service instance.

Parameters

  • [in] config_node: The YAML configuration file, structured as defined in the is::core::internal::Config::parse() method documentation, that should be provided to Integration Service to successfully start a communication between two or more applications using different communication protocols.

  • [in] is_prefixes: Global prefix paths for Integration Service to search for configuration files or mix files.

    These act as a complement to the already existing environment variables created during compilation/installation steps by CMake.

  • [in] middleware_prefixes: Prefix paths specific to a certain middleware. Used when loading a middleware’s plugin, that is, its SystemHandle implementation.