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 function calls shutdown() implicitly. Calling this function destroys all object adapters, and closes all outgoing connections. This function 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 function calls 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 function calls ObjectAdapter.waitForDeactivate() on all object adapters created by this communicator. In a client application that does not accept incoming connections, this function 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 awaiting 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.

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

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

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

Creates a new object adapter with endpoints. This function sets the property name.Endpoints, and then calls createObjectAdapter(). It is provided as a convenience function. Calling this function 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

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

Creates a new object adapter with a router. This function creates a routed object adapter. Calling this function 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

getDefaultObjectAdapter() → ObjectAdapter | None¶

Gets the object adapter that is associated by default with new outgoing connections created by this communicator. This function 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 function has no effect on existing outgoing connections, or on incoming connections.

Parameters:: adapter (ObjectAdapter | None) – The object adapter to associate with new outgoing connections.

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 function has no effect on existing proxies.

Notes

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

Parameters:: router (RouterPrx | None) – The new default router. Use None to remove the default router.

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

setDefaultLocator(locator: LocatorPrx | None)¶

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

Notes

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

Parameters:: locator (LocatorPrx | None) – The new default locator. Use None to remove the default locator.

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.

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]

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 Locator, this function registers the Admin’s Process facet with the Locator’s LocatorRegistry.

Parameters:

adminAdapter (ObjectAdapter | None) – The object adapter used to host the Admin object; if it is None and Ice.Admin.Endpoints is set, this function 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 function is called more than once.

getAdmin() → ObjectPrx | None¶

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

getAdmin 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 getAdmin 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, getAdmin 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 | None, 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.

Return type:

None

removeAdminFacet(facet: str) → Object¶

Removes a facet from the Admin object.

Parameters:: facet (str) – The name of the Admin facet.
Returns:: The servant associated with this Admin facet.
Return type:: Object
Raises:: NotRegisteredException – If no facet with the given name is registered.

findAdminFacet(facet: str) → Object | 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.
Return type:: Object | None

findAllAdminFacets() → dict[str, Object]¶

Returns a map of all facets of the Admin object.

Returns:: A collection containing all the facet names and servants of the Admin object.
Return type:: dict[str, Object]