---
title: "Communicator"
url: https://docs.zeroc.com/ice/3.8/runtime/communicator
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Communicator

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/runtime/communicator/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/runtime/communicator/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/runtime/communicator/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/runtime/communicator/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/runtime/communicator/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/runtime/communicator/php.md), [Python](https://docs.zeroc.com/ice/3.8/runtime/communicator/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/runtime/communicator/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/runtime/communicator/swift.md).

A communicator ([C++](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1Communicator.html), [C#](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.Communicator.html), [Java](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/Communicator.html), [JavaScript](https://code.zeroc.com/ice/3.8/api/javascript/Ice/Communicator.html), [Python](https://code.zeroc.com/ice/3.8/api/python/Ice.Communicator.html), and [Swift](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/communicator)) is the entry point into the Ice runtime. You create proxies with a communicator, and each communicator has its own:

- **Outgoing connections** The communicator establishes and caches the connections that invocations on its proxies use.
- **Client-side thread pool** This [thread pool](https://docs.zeroc.com/ice/3.8/runtime/threading-model.md) processes the messages received on the outgoing connections.
- **Object adapters** The communicator creates the [object adapters](https://docs.zeroc.com/ice/3.8/runtime/dispatch.md) that dispatch incoming requests to your servants.
- **Properties** Each communicator holds a [property set](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration.md). These properties configure this communicator, and an Ice service or an application that uses this communicator can read its own properties from the same set.
- **Logger** The [logger](https://docs.zeroc.com/ice/3.8/administration/logger-facility.md) of a communicator receives the log messages of the Ice runtime.

Most applications use a single communicator, but an application can create several communicators when needed.

## Creating a Communicator

> **C++**
>
> You create a communicator by calling `Ice::initialize`:
>
> ```cpp
> #include <Ice/Ice.h>
>
> int
> main(int argc, char* argv[])
> {
>     Ice::CommunicatorPtr communicator = Ice::initialize(argc, argv);
>     // ...
> }
> ```
>
> `initialize` takes `argc` by reference and the argument vector `argv`. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and removes these arguments from `argc` and `argv`.

> **C#**
>
> You create a communicator by using its constructor, for example:
>
> ```csharp
> await using var communicator = new Ice.Communicator(ref args);
> ```
>
> The constructor takes the command-line arguments passed to `Main`. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and removes these arguments from `args`.
>
> `Ice.Communicator` implements both `IDisposable` and `IAsyncDisposable`. This allows you to create and clean up your communicator with `await using` in async applications (as shown above). In synchronous code, you can use instead:
>
> ```csharp
> // In synchronous code.
> using var communicator = new Ice.Communicator(ref args);
> ```

> **Java**
>
> You create a communicator by using its constructor, for example:
>
> ```java
> class Client {
>     public static void main(String[] args) {
>         try (Communicator communicator = new Communicator(args)) {
>             // ...
>         }
>     }
> }
> ```
>
> The constructor takes the command-line arguments passed to `main`. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and leaves `args` unchanged. To get the remaining arguments, call the constructor that also accepts a `List<String> remainingArgs`, which it fills with the arguments that do not name an Ice property.
>
> `Communicator` implements `AutoCloseable`. This allows you to create and clean up your communicator in a try-with-resources statement as shown above.

> **JavaScript**
>
> You create a communicator by using its constructor, for example:
>
> ```typescript
> import { Ice } from "@zeroc/ice";
>
> await using communicator = new Ice.Communicator(process.argv);
> ```
>
> This constructor takes the command-line arguments. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and removes these arguments from the array.
>
> In a browser application, call the constructor without arguments, or with [initialization data](https://docs.zeroc.com/ice/3.8/runtime/communicator/js.md#initialization-data).
>
> `Communicator` implements `[Symbol.asyncDispose]()`, so `await using` destroys the communicator when it goes out of scope, as shown above. Without `await using`, call `await communicator.destroy()` when you no longer need it.

> **MATLAB**
>
> You create a communicator with the `Ice.Communicator` constructor:
>
> ```matlab
> communicator = Ice.Communicator(args);
> ```
>
> The constructor takes the command-line arguments and [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property. The constructor also accepts the `Properties` and `SliceLoader` name-value arguments; when you pass both the command-line arguments and `Properties`, the properties set by the arguments override those in `Properties`.
>
> The constructor leaves `args` unchanged. To get the remaining arguments, create the properties yourself and pass them to the constructor:
>
> ```matlab
> [props, remArgs] = Ice.Properties(args);
> communicator = Ice.Communicator(Properties = props);
> ```
>
> To destroy the communicator when the function that created it returns, schedule the call to `destroy` with `onCleanup`:
>
> ```matlab
> cleanup = onCleanup(@() communicator.destroy());
> ```
>
> MATLAB clears `cleanup` when the function returns, which calls `destroy` on the communicator.

> **PHP**
>
> You create a communicator by calling `Ice\initialize`, for example:
>
> ```php
> <?php
> require_once 'Ice.php';
>
> $communicator = Ice\initialize($argv);
> ```
>
> `Ice\initialize` takes the argument array of the script. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and removes these arguments from the array.
>
> `$argv` holds command-line arguments only when PHP runs the script from the command line. A script that handles a web request calls `Ice\initialize` without arguments, or with [initialization data](https://docs.zeroc.com/ice/3.8/runtime/communicator/php.md#initialization-data).

> **Python**
>
> You create a communicator by using its constructor, for example:
>
> ```py
> import Ice
> import sys
>
> def main():
>     with Ice.Communicator(sys.argv) as communicator:
>         ...
> ```
>
> The `Ice.Communicator` constructor takes the command-line arguments of the program. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and removes these arguments from the list.
>
> `Communicator` implements the [Python context manager protocol](https://peps.python.org/pep-0343/), which cleans up the communicator automatically at the end of the with block.
>
> `async with` is preferred in an async context. For example:
>
> ```py
> import Ice
> import asyncio
> import sys
>
> async def main():
>     async with Ice.Communicator(
>         sys.argv,
>         eventLoop=asyncio.get_running_loop()) as communicator:
>         ...
> ```

> **Ruby**
>
> You create a communicator by calling `Ice.initialize`, for example:
>
> ```ruby
> require 'Ice'
>
> Ice.initialize(ARGV) do |communicator|
>     ...
> end
> ```
>
> `Ice.initialize` takes the command-line arguments of the program. It [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property, and removes these arguments from the array.
>
> With a block, `Ice.initialize` destroys the communicator when the block completes, including when it raises an exception. Without a block, `Ice.initialize` returns the communicator, and you call `destroy` on it when you no longer need it.

> **Swift**
>
> You create a communicator by calling [Ice.initialize](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/initialize(_:)-9a9sk), for example:
>
> ```swift
> let communicator = try Ice.initialize(CommandLine.arguments)
> ```
>
> `initialize` [sets a property](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md) for each argument that names an Ice property. This overload does not modify the argument array; the overload that takes an `inout` array removes these arguments from it.
>
> Call `destroy` on the communicator when you no longer need it. In a function, `defer` destroys it when the function returns:
>
> ```swift
> let communicator = try Ice.initialize(CommandLine.arguments)
> defer {
>     communicator.destroy()
> }
> ```

## Destroying a Communicator

> **PHP**
>
> In PHP terminology, a *request* is the execution of a PHP script on behalf of a web client. Each request has its own execution context, and PHP releases the resources a request acquired, including the objects created by the Ice for PHP extension, when the request completes. A PHP worker process, for example in a PHP-FPM pool, handles many requests over its lifetime.
>
> When a request completes, Ice for PHP destroys every communicator that the request created and did not [register](https://docs.zeroc.com/ice/3.8/runtime/communicator/php.md#registered-communicators), so a script usually does not call `destroy`.

(C++, C#, Java, JavaScript, MATLAB, Python, Ruby, and Swift: Destroy a communicator when you no longer need it.) Destroying a communicator closes its connections (C++, C#, Java, JavaScript, Python, and Swift: destroys its object adapters, waits for the dispatches that are still running to complete) and releases its resources.

> **C++**
>
> An `Ice::CommunicatorHolder` calls `destroy` on its communicator when it goes out of scope:
>
> ```cpp
> Ice::CommunicatorPtr communicator = Ice::initialize(argc, argv);
> Ice::CommunicatorHolder communicatorHolder{communicator};
> ```
>
> To take over the destruction of the communicator held by a `CommunicatorHolder`, call `release`.

> **PHP**
>
> Creating a communicator in each request means loading its configuration and opening its connections in each request, and closing these connections when the request completes. Ice for PHP provides two ways to avoid this overhead:
>
> - A [pre-configured property set](https://docs.zeroc.com/ice/3.8/runtime/communicator/php.md#property-sets) avoids parsing a configuration file in each request.
> - A [registered communicator](https://docs.zeroc.com/ice/3.8/runtime/communicator/php.md#registered-communicators) keeps its connections open between the requests that the same PHP process handles.
>
> ## Registered Communicators
>
> A registered communicator outlives the request that created it: later requests that the same PHP process handles can retrieve it by name and reuse it, with its open connections. A registered communicator is local to the process that created it. PHP-FPM and similar servers spread requests over a pool of worker processes, so two requests, even from the same session, can run in different processes, and each process creates and registers its own communicator.
>
> The API for registered communicators consists of three functions:
>
> - `Ice\register($communicator, $name, $expires=0)` Registers a communicator with the given name. Returns false if another communicator is already registered with this name, and true otherwise. You can register the same communicator under several names.
> - `Ice\find($name)` Returns the communicator registered with the given name, or `null` if there is none.
> - `Ice\unregister($name)` Removes the registration with the given name. Returns true if a communicator was registered with this name, and false otherwise.
>
> An application typically uses registered communicators as follows:
>
> ```php
> <?php
> require_once 'Ice.php';
> ...
>
> $communicator = Ice\find('Greeter');
> if ($communicator === null) {
>     $communicator = Ice\initialize();
>     Ice\register($communicator, 'Greeter');
> }
> ```
>
> If another request of the same process registers a communicator named `Greeter` in the meantime, `Ice\register` returns false, and this request uses its own communicator, which Ice for PHP destroys when the request completes.
>
> Note that communicators consume resources such as threads, sockets, and memory, therefore an application should be designed to minimize the number of communicators it registers. Using a suitable expiration timeout prevents registered communicators from accumulating indefinitely.
>
> ### Lifetime of a Registered Communicator
>
> Ice for PHP destroys a registered communicator when one of the following happens:
>
> - **It expires.** When `$expires` is greater than zero, Ice for PHP destroys the communicator and removes all its registrations once no script has retrieved it with `Ice\find` for `$expires` minutes. Each call to `Ice\register` replaces the expiration time of the communicator, and the default value, 0, means the communicator never expires.
> - **You remove its last registration.** After `Ice\unregister` removes the last name of a communicator, Ice for PHP destroys the communicator once every request that created it or retrieved it with `Ice\find` has completed.
> - **The process terminates.**
>
> Destroying a registered communicator yourself also removes all its registrations.
>
> ### Security Considerations for Registered Communicators
>
> Any script that runs in the same PHP process can retrieve a registered communicator by its name: a registration name is not an access control. For example, if a malicious script obtains a registered communicator that is configured with SSL credentials, it can make secure invocations as if it were the trusted script. Run applications that do not trust each other in separate PHP processes, such as separate PHP-FPM pools.

> **C++, C#, Java, JavaScript, PHP, Python, Ruby, and Swift**
>
> ## Initialization Data
>
> InitializationData ([C++](https://code.zeroc.com/ice/3.8/api/cpp/structIce_1_1InitializationData.html), [C#](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.InitializationData.html), [Java](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/InitializationData.html), [JavaScript](https://code.zeroc.com/ice/3.8/api/javascript/Ice/InitializationData.html), [PHP](https://code.zeroc.com/ice/3.8/api/php/classes/Ice-InitializationData.html), [Python](https://code.zeroc.com/ice/3.8/api/python/Ice.InitializationData.html), [Ruby](https://code.zeroc.com/ice/3.8/api/ruby/Ice/InitializationData.html), and [Swift](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/initializationdata)) holds the options you can supply when you create a communicator, such as its properties (C++, C#, Java, JavaScript, PHP, Python, and Swift: and its logger). Set these options in an `InitializationData` object, and create the communicator with this object.

> **C++**
>
> `initialize` takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from `argc` and `argv` and set them in the initialization data:
>
> ```cpp
> Ice::InitializationData initData;
> initData.properties = std::make_shared<Ice::Properties>(argc, argv);
> // ... set other initData fields ...
> Ice::CommunicatorPtr communicator = Ice::initialize(std::move(initData));
> ```

> **C#**
>
> The constructor takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from `args` and set them in the initialization data:
>
> ```csharp
> var initData = new Ice.InitializationData
> {
>     properties = new Ice.Properties(ref args),
>     // ... set other initData fields ...
> };
> await using var communicator = new Ice.Communicator(initData);
> ```

> **Java**
>
> The constructor takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from `args` and set them in the initialization data:
>
> ```java
> var initData = new InitializationData();
> initData.properties = new Properties(args);
> // ... set other initData fields ...
> try (var communicator = new Communicator(initData)) {
>     // ...
> }
> ```

> **JavaScript**
>
> The constructor takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from the arguments and set them in the initialization data:
>
> ```typescript
> const initData = new Ice.InitializationData();
> initData.properties = new Ice.Properties(process.argv);
> // ... set other initData fields ...
> await using communicator = new Ice.Communicator(initData);
> ```

> **PHP**
>
> For example, the following script creates the communicator's properties from a configuration file:
>
> ```php
> <?php
> require_once 'Ice.php';
>
> $properties = Ice\createProperties();
> $properties->load("config.client");
>
> $initData = new Ice\InitializationData();
> $initData->properties = $properties;
>
> $communicator = Ice\initialize($initData);
> ```
>
> ## Property Sets
>
> A PHP application can manually construct a [property set](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/php.md) for configuring its communicator. The Ice for PHP extension also provides a PHP-specific property set API that helps to minimize the overhead associated with initializing a communicator, allowing you to configure a default property set along with an unlimited number of named property sets (or *profiles*).
>
> You can populate a property set using a configuration file, command-line options, or both. Property sets are initialized using the normal Ice semantics: command-line options override any settings from a configuration file.
>
> Ice for PHP creates these property sets when the PHP process loads the Ice for PHP extension, so changes to their configuration take effect only when the PHP processes restart. A relative path name for a configuration file is usually evaluated relative to the working directory of the PHP process.
>
> ### Default Property Set
>
> The INI directives `ice.config` and `ice.options` specify the configuration file and the command-line options for the default property set, respectively. These directives must appear in PHP's configuration file, which is usually named `php.ini`:
>
> ```ini
> ; Snippet from php.ini on Linux
> extension=IcePHP.so
> ice.config=/opt/MyApp/default.cfg
> ice.options="--Ice.Trace.Network=1"
> ```
>
> ### Profiles
>
> Profiles are useful when several unrelated applications execute in the same web server, or when a script needs to choose among multiple configurations. To configure your profiles, add an `ice.profiles` directive to PHP's configuration file. The value of this directive is a file containing profile definitions:
>
> ```ini
> ; Snippet from php.ini on Linux
> ice.profiles=/opt/MyApp/profiles
> ```
>
> The profile definition file uses INI syntax:
>
> ```ini
> [Production]
> config=/opt/MyApp/prod.cfg
> options="..."
>
> [Debug]
> config=/opt/MyApp/debug.cfg
> options="--Ice.Trace.Network=3 ..."
> ```
>
> The name of each profile is enclosed in square brackets. The configuration file and command-line options for each profile are defined using the `config` and `options` entries, respectively.
>
> ### Using Property Sets
>
> The `Ice\getProperties` function allows a script to obtain a copy of a property set. When called without an argument, or with an empty string, the function returns the default property set. Otherwise, the function expects the name of a configured profile and returns the property set associated with that profile. The return value is an instance of `Ice\Properties`, or `null` if no matching profile was found.
>
> Note that Ice for PHP always creates the default property set, which is empty if the `ice.config` and `ice.options` directives are not defined. Also note that changes a script might make to a property set returned by this function have no effect on other requests because the script is modifying a *copy* of the original property set.
>
> The following script uses the default property set instead of loading a configuration file in each request:
>
> ```php
> <?php
> require_once 'Ice.php';
> require_once 'Greeter.php';
>
> $initData = new Ice\InitializationData();
> $initData->properties = Ice\getProperties();
>
> $communicator = Ice\initialize($initData);
>
> $greeter = VisitorCenter\GreeterPrxHelper::uncheckedCast(
>     $communicator->propertyToProxy("Greeter.Proxy"));
>
> echo $greeter->greet("alice"), "\n";
> ```

> **Python**
>
> The constructor takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from the arguments and set them in the initialization data:
>
> ```py
> initData = Ice.InitializationData()
> initData.properties = Ice.Properties(sys.argv)
> # ... set other initData fields ...
> with Ice.Communicator(initData=initData) as communicator:
>     ...
> ```

> **Ruby**
>
> `Ice.initialize` takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from the arguments and set them in the initialization data:
>
> ```ruby
> initData = Ice::InitializationData.new
> initData.properties = Ice.createProperties(ARGV)
> # ... set other initData fields ...
> Ice.initialize(initData) do |communicator|
>     ...
> end
> ```

> **Swift**
>
> `initialize` takes either the command-line arguments or an `InitializationData`. To set properties from the arguments when you pass initialization data, create the properties from the arguments and set them in the initialization data:
>
> ```swift
> var initData = Ice.InitializationData()
> initData.properties = try Ice.createProperties(CommandLine.arguments)
> // ... set other initData fields ...
> let communicator = try Ice.initialize(initData)
> defer {
>     communicator.destroy()
> }
> ```

## See Also

- [Setting Properties on the Command Line](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/setting-properties-on-the-command-line.md)
- [The Properties Class](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/properties-class.md)
