On this page:
Initializing the Ice Run Time with
Every Ice-based application needs to initialize the Ice run time, and this initialization returns an
Communicator is a local C++ object that represents an instance of the Ice run time. Most Ice-based applications create and use a single
Communicator object, although it is possible and occasionally desirable to have multiple
Communicator objects in the same application or program.
You initialize the Ice run time by calling the C++ function
Ice::initialize, for example:
initialize accepts a C++ reference to
argc and an argument vector
argv. The function scans the argument vector for any command-line options that are relevant to the Ice run time; any such options are removed from the argument vector so, when
initialize returns, the only options and arguments remaining are those that concern your application. If anything goes wrong during initialization,
initialize throws an exception.
Ice::initialize has additional overloads to permit other information to be passed to the Ice run time.
initialize is a low-level function, as you need to explicitly call
destroy on the returned
Communicator object when you're done with Ice, typically just before returning from
destroy member function is responsible for finalizing the Ice run time. In particular, in a server,
destroy waits for any operation implementations that are still executing to complete. In addition,
destroy ensures that any outstanding threads are joined with and reclaims a number of operating system resources, such as file descriptors and memory.
The general shape of the
main function of an Ice-based application is therefore as follows:
This code is a little bit clunky, as we need to make sure the communicator gets destroyed in all paths, including when an exception is thrown. As a result, most of the time, you should not call
initialize directly: you should use instead a helper class that calls
initialize and ensures the resulting communicator gets eventually destroyed.
Ice::CommunicatorHolder RAII Helper Class
CommunicatorHolder is a small RAII helper class that creates a
Communicator in its constructor (by calling
initialize) and destroys this communicator in its destructor.
CommunicatorHolder, our typical
main function becomes much simpler:
Ice::CommunicatorHolder is defined as follows:
Let's examine each of these functions:
This default constructor creates an empty holder (holds no Communicator).
CommunicatorHolder(int& argc, const char* argv, const InitializationData& initData = InitializationData(), int version = ICE_INT_VERSION)and many more constructors
Each of these constructor calls
initializewith the provided parameters; the new
CommunicatorHolderthen holds the resulting
Communicatorin a private data member (not shown).
This constructor adopts the given communicator: the
CommunicatorHolderbecomes responsible to call
CommunicatorHolder& operator=(const CommunicatorPtr&)This assignment operator destroys the communicator held by this
CommunicatorHolder, then adopts the provided communicator.
~CommunicatorHolder()The destructor calls
destroyon the communicator held by this
operator bool() constReturns
const CommunicatorPtr& communicator() constThis function gives read-only access to the communicator held by this
const CommunicatoPtr& operator->() const
This arrow operator allows you to use a
CommunicatorHolderjust like a
Communicatorobject. For example:
is equivalent to:
This function returns the communicator held by
CommunicatorHolderto the caller, and the caller becomes responsible to destroy this communicator.
CommunicatorHolderno longer holds a communicator after this call.
The default constructor of
CommunicatorHolder does nothing:
If you want to create a
CommunicatorHolder that holds a
Communicator created by
initialize with no args, you can write: