The main entry point to the Ice run time is represented by the local interface Ice::Communicator
. An instance of Ice::Communicator
is associated with a number of run-time resources:
Ice::Logger
interface and determines how log messages that are produced by the Ice run time are handled.Ice::Router
interface. Routers are used by Glacier2 to implement the firewall functionality of Ice.Ice::PluginManager
interface and provides access to the set of plug-ins for a communicator.Object adapters and objects that use different communicators are completely independent from each other. Specifically:
Typically, servers use only a single communicator but, occasionally, multiple communicators can be useful. For example, IceBox, uses a separate communicator for each Ice service it loads to ensure that different services cannot interfere with each other. Multiple communicators are also useful to avoid thread starvation: if one service runs out of threads, this leaves the remaining services unaffected.
The communicator's interface is defined in Slice. Part of this interface looks as follows:
module Ice { local interface Communicator { string proxyToString(Object* obj); Object* stringToProxy(string str); PropertyDict proxyToProperty(Object* proxy, string property); Object* propertyToProxy(string property); Identity stringToIdentity(string str); string identityToString(Identity id); ObjectAdapter createObjectAdapter(string name); ObjectAdapter createObjectAdapterWithEndpoints(string name, string endpoints); ObjectAdapter createObjectAdapterWithRouter(string name, Router* rtr); void shutdown(); void waitForShutdown(); bool isShutdown(); void destroy(); // ... }; // ... }; |
The communicator offers a number of operations:
proxyToString
stringToProxy
proxyToString
on the communicator, you can also use the ice_toString
proxy method to stringify it. However, you can only stringify non-null proxies that way — to stringify a null proxy, you must use proxyToString
. (The stringified representation of a null proxy is the empty string.)proxyToProperty
propertyToProxy
proxyToProperty
returns the set of proxy properties for the supplied proxy. The property
parameter specifies the base name for the properties in the returned set. propertyToProxy
retrieves the configuration property with the given name and converts its value into a proxy. A null proxy is returned if no property is found with the specified name.identityToString
stringToIdentity
createObjectAdapter
createObjectAdapterWithEndpoints
createObjectAdapterWithRouter
createObjectAdapter
determines its transport endpoints from configuration information, createObjectAdapterWithEndpoints
allows you to supply the transport endpoints for the new adapter. Typically, you should use createObjectAdapter
in preference to createObjectAdapterWithEndpoints
. Doing so keeps transport-specific information, such as host names and port numbers, out of the source code and allows you to reconfigure the application by changing a property (and so avoid recompilation when a transport endpoint needs to be changed). createObjectAdapterWithRouter
creates a routed object adapter that allows clients to receive callbacks from servers that are behind a router. Ice.Warn.UnknownProperties
.shutdown
shutdown
is called are allowed to complete normally. shutdown
does not wait for these operations to complete; when shutdown
returns, you know that no new incoming requests will be dispatched, but operations that were already in progress at the time you called shutdown
may still be running. You can wait for still-executing operations to complete by calling waitForShutdown
.shutdown
either fail with a ConnectFailedException
or are transparently redirected to a new instance of the server (via IceGrid).shutdown
initiates deactivation of all object adapters associated with the communicator, so attempts to use an adapter once shutdown
has completed raise an ObjectAdapterDeactivatedException
.waitForShutdown
waitForShutdown
simply waits until another thread has called shutdown
or destroy
.isShutdown
shutdown
has been invoked on the communicator. A return value of true does not necessarily indicate that the shutdown process has completed, only that it has been initiated. An application that needs to know whether shutdown is complete can call waitForShutdown
. If the blocking nature of waitForShutdown
is undesirable, the application can invoke it from a separate thread.destroy
destroy
before you leave the main
function of your program. Failure to do so results in undefined behavior. destroy
before leaving main
is necessary because destroy
waits for all running threads to terminate before it returns. If you leave main
without calling destroy
, you will leave main
with other threads still running; many threading packages do not allow you to do this and end up crashing your program. destroy
without calling shutdown
, the call waits for all executing operation invocations to complete before it returns (that is, the implementation of destroy
implicitly calls shutdown
followed by waitForShutdown
). shutdown
(and, therefore, destroy
) deactivates all object adapters that are associated with the communicator. Since destroy
blocks until all operation invocations complete, a servant will deadlock if it invokes destroy
on its own communicator while executing a dispatched operation. destroy
while operations are still executing causes those operations to terminate with a CommunicatorDestroyedException
.