Ice.Communicator¶

final class Ice.Communicator(args: list[str] | None = None, eventLoop: AbstractEventLoop | None = None)¶

final class Ice.Communicator(*, initData: InitializationData | None = None)

Bases: object

Communicator is the central object in Ice. Its responsibilities include:

creating and managing outgoing connections
executing callbacks in its client thread pool
creating and destroying object adapters
loading plug-ins
managing properties (configuration), retries, logging, instrumentation, and more.

A communicator is usually the first object you create when programming with Ice. You can create multiple communicators in a single program, but this is not common.

Example

The following example shows how to create a communicator and use the async with statement to ensure that the communicator is properly destroyed.

async def main():
    async with Ice.Communicator(
        sys.argv, eventLoop=asyncio.get_running_loop()
    ) as communicator:
        ...

if __name__ == "__main__":
    asyncio.run(main())

Parameters:

args (list[str] | None)
eventLoop (asyncio.AbstractEventLoop | None)
initData (InitializationData | None)

property eventLoopAdapter: EventLoopAdapter | None¶

Returns this communicator’s event loop adapter, or None if the communicator does not have one.

Returns:: The event loop adapter used by this communicator.
Return type:: EventLoopAdapter | None

destroy() → None¶

Destroys this communicator. This method calls shutdown() implicitly. Calling this method destroys all object adapters, and closes all outgoing connections. This method waits for all outstanding dispatches to complete before returning. This includes “bidirectional dispatches” that execute on outgoing connections.

Return type:: None

destroyAsync() → Awaitable[None]¶

Destroys this communicator asynchronously.

See destroy().

Return type:: Awaitable[None]

shutdown() → None¶

Shuts down this communicator. This method calls Ice.ObjectAdapter.deactivate() on all object adapters created by this communicator. Shutting down a communicator has no effect on outgoing connections.

Return type:: None

waitForShutdown() → None¶

Waits for shutdown to complete. This method calls Ice.ObjectAdapter.waitForDeactivate() on all object adapters created by this communicator. In a client application that does not accept incoming connections, this method returns as soon as another thread calls shutdown() or destroy() on this communicator.

Return type:: None

shutdownCompleted() → Awaitable[None]¶

Returns an Awaitable that completes when the communicator’s shutdown completes. This task always completes successfully.

Notes

The shutdown of a communicator completes when all its incoming connections are closed. Awaiting this task is equivalent to calling waitForShutdown().

Returns:: An awaitable that completes upon shutdown completion.
Return type:: Awaitable[None]

isShutdown() → bool¶

Checks whether or not shutdown() was called on this communicator.

Returns:: True if shutdown() was called on this communicator, False otherwise
Return type:: bool

stringToProxy(str: str) → ObjectPrx | None¶

Converts a stringified proxy into a proxy.

Parameters:

str (str) – The stringified proxy to convert into a proxy.

Returns:

The proxy, or None if str is an empty string.

Return type:

ObjectPrx | None

Raises:

ParseException – If str is not a valid proxy string.
CommunicatorDestroyedException – If the communicator has been destroyed.

proxyToString(proxy: ObjectPrx | None) → str¶

Converts a proxy into a string.

Parameters:: proxy (ObjectPrx | None) – The proxy to convert into a stringified proxy.
Returns:: The stringified proxy, or an empty string if proxy is None.
Return type:: str

propertyToProxy(property: str) → ObjectPrx | None¶

Converts a set of proxy properties into a proxy. The “base” name supplied in the property argument refers to a property containing a stringified proxy, such as MyProxy=id:tcp -h localhost -p 10000. Additional properties configure local settings for the proxy.

Parameters:

property (str) – The base property name.

Returns:

The proxy, or None if the property is not set.

Return type:

ObjectPrx | None

Raises:

ParseException – If the property value is not a valid proxy string.
CommunicatorDestroyedException – If the communicator has been destroyed.

proxyToProperty(proxy: ObjectPrx, property: str) → dict[str, str]¶

Converts a proxy into a set of proxy properties.

Parameters:

proxy (ObjectPrx) – The proxy.
property (str) – The base property name.

Returns:

The property set.

Return type:

dict[str, str]

identityToString(identity: Identity) → str¶

Converts an identity into a string.

Parameters:: identity (Identity) – The identity to convert into a string.
Returns:: The “stringified” identity.
Return type:: str

createObjectAdapter(name: str) → ObjectAdapter¶

Creates a new object adapter. The endpoints for the object adapter are taken from the property name.Endpoints.

It is legal to create an object adapter with the empty string as its name. Such an object adapter is accessible via bidirectional connections or by collocated invocations.

Parameters:: name (str) – The object adapter name.
Returns:: The new object adapter.
Return type:: ObjectAdapter
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

createObjectAdapterWithEndpoints(name: str, endpoints: str) → ObjectAdapter¶

Creates a new object adapter with endpoints. This method sets the property name.Endpoints, and then calls createObjectAdapter(). It is provided as a convenience method. Calling this method with an empty name will result in a UUID being generated for the name.

Parameters:

name (str) – The object adapter name.
endpoints (str) – The endpoints of the object adapter.

Returns:

The new object adapter.

Return type:

ObjectAdapter

Raises:

CommunicatorDestroyedException – If the communicator has been destroyed.

createObjectAdapterWithRouter(name: str, router: RouterPrx) → ObjectAdapter¶

Creates a new object adapter with a router. This method creates a routed object adapter. Calling this method with an empty name will result in a UUID being generated for the name.

Parameters:

name (str) – The object adapter name.
router (RouterPrx) – The router.

Returns:

The new object adapter.

Return type:

ObjectAdapter

Raises:

CommunicatorDestroyedException – If the communicator has been destroyed.

getDefaultObjectAdapter() → ObjectAdapter | None¶

Gets the object adapter that is associated by default with new outgoing connections created by this communicator. This method returns None unless you set a non-None default object adapter using setDefaultObjectAdapter().

Returns:: The object adapter associated by default with new outgoing connections.
Return type:: ObjectAdapter | None
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

setDefaultObjectAdapter(adapter: ObjectAdapter | None)¶

Sets the object adapter that will be associated with new outgoing connections created by this communicator. This method has no effect on existing outgoing connections, or on incoming connections.

Parameters:: adapter (ObjectAdapter | None) – The object adapter to associate with new outgoing connections.
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

getImplicitContext() → ImplicitContext | None¶

Gets the implicit context associated with this communicator.

Returns:: The implicit context associated with this communicator; returns None when the property Ice.ImplicitContext is not set or is set to None.
Return type:: ImplicitContext | None

getProperties() → Properties¶

Gets the properties of this communicator.

Returns:: This communicator’s properties.
Return type:: Properties

getLogger() → Logger¶

Gets the logger of this communicator.

Returns:: This communicator’s logger.
Return type:: Logger

getDefaultRouter() → RouterPrx | None¶

Gets the default router of this communicator.

Returns:: The default router of this communicator, or None if no default router has been set.
Return type:: RouterPrx | None
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

setDefaultRouter(router: RouterPrx | None)¶

Sets the default router of this communicator. All newly created proxies will use this default router. This method has no effect on existing proxies.

Notes

You can set a router for an individual proxy by calling Ice.ObjectPrx.ice_router() on the proxy.

Parameters:: router (RouterPrx | None) – The new default router. Use None to remove the default router.
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

getDefaultLocator() → LocatorPrx | None¶

Gets the default locator of this communicator.

Returns:: The default locator of this communicator, or None if no default locator has been set.
Return type:: LocatorPrx | None
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

setDefaultLocator(locator: LocatorPrx | None)¶

Sets the default locator of this communicator. All newly created proxies will use this default locator. This method has no effect on existing proxies or object adapters.

Notes

You can set a locator for an individual proxy by calling Ice.ObjectPrx.ice_locator() on the proxy, or for an object adapter by calling Ice.ObjectAdapter.setLocator() on the object adapter.

Parameters:: locator (LocatorPrx | None) – The new default locator. Use None to remove the default locator.
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

flushBatchRequests(compress: CompressBatch)¶

Flushes any pending batch requests of this communicator. This means all batch requests invoked on fixed proxies for all connections associated with the communicator. Errors that occur while flushing a connection are ignored.

Parameters:: compress (CompressBatch) – Specifies whether or not the queued batch requests should be compressed before being sent over the wire.
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

flushBatchRequestsAsync(compress: CompressBatch) → Awaitable[None]¶

Parameters:: compress (CompressBatch) – Specifies whether or not the queued batch requests should be compressed before being sent over the wire.
Returns:: An Awaitable that completes when all batch requests have been sent.
Return type:: Awaitable[None]
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed. This exception is raised synchronously.

createAdmin(adminAdapter: ObjectAdapter | None, adminId: Identity) → ObjectPrx¶

Adds the Admin object with all its facets to the provided object adapter. If Ice.Admin.ServerId is set and the provided object adapter has a Ice.LocatorPrx, this method registers the Admin’s Process facet with the locator’s Ice.LocatorRegistryPrx.

Parameters:

adminAdapter (ObjectAdapter | None) – The object adapter used to host the Admin object; if it is None and Ice.Admin.Endpoints is set, this method uses the Ice.Admin object adapter, after creating and activating this adapter.
adminId (Identity) – The identity of the Admin object.

Returns:

A proxy to the main (“”) facet of the Admin object.

Return type:

ObjectPrx

Raises:

InitializationException – If this method is called more than once.
CommunicatorDestroyedException – If the communicator has been destroyed.

getAdmin() → ObjectPrx | None¶

Gets a proxy to the main facet of the Admin object.

This method also creates the Admin object and creates and activates the Ice.Admin object adapter to host this Admin object if Ice.Admin.Endpoints is set. The identity of the Admin object created by this method is {value of Ice.Admin.InstanceName}/admin, or {UUID}/admin when Ice.Admin.InstanceName is not set. If Ice.Admin.DelayCreation is 0 or not set, this method is called by the communicator initialization, after initialization of all plugins.

Returns:: A proxy to the main (“”) facet of the Admin object, or None if no Admin object is configured.
Return type:: ObjectPrx | None
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

addAdminFacet(servant: Object, facet: str) → None¶

Adds a new facet to the Admin object.

Parameters:

servant (Object) – The servant that implements the new Admin facet.
facet (str) – The name of the new Admin facet.

Raises:

AlreadyRegisteredException – If a facet with the same name is already registered.
CommunicatorDestroyedException – If the communicator has been destroyed.

Return type:

None

removeAdminFacet(facet: str) → Object | None¶

Removes a facet from the Admin object.

Parameters:

facet (str) – The name of the Admin facet.

Returns:

The servant associated with this Admin facet, or None if this facet is implemented by the Ice runtime. See findAdminFacet() for the list of such facets.

Return type:

Object | None

Raises:

NotRegisteredException – If no facet with the given name is registered.
CommunicatorDestroyedException – If the communicator has been destroyed.

findAdminFacet(facet: str) → Object | IcePy.NativePropertiesAdmin | None¶

Returns a facet of the Admin object.

Parameters:: facet (str) – The name of the Admin facet.
Returns:: The servant associated with this Admin facet, or None if no facet is registered with the given name, or if this facet is implemented by the Ice runtime and has no Python servant.
Return type:: Object | IcePy.NativePropertiesAdmin | None
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.

Notes

Some Admin facets are implemented by the Ice runtime itself rather than by a Python servant. The Properties facet is returned as an Ice.NativePropertiesAdmin, which is not an Ice.Object. The other runtime facets, such as Process and Metrics, are reported as None even though they are registered and reachable through the Admin object.

findAllAdminFacets() → dict[str, Object | IcePy.NativePropertiesAdmin]¶

Returns a map of all facets of the Admin object.

Returns:: A collection containing all the facet names and servants of the Admin object. Facets implemented by the Ice runtime with no Python servant are omitted; see findAdminFacet().
Return type:: dict[str, Object | IcePy.NativePropertiesAdmin]
Raises:: CommunicatorDestroyedException – If the communicator has been destroyed.