The Process Facet

Obtaining the Local Process Facet

We already showed how to obtain a proxy for a remote administrative facet, but suppose you want to interact with the facet in your local address space. The code below shows the necessary steps:

// It's nullptr when the facet is not enabled
Ice::ProcessPtr process =
    communicator->findAdminFacet<Ice::Process>("Process");

Application Requirements for the Process Facet

The default implementation of the Process facet requires cooperation from an application in order to successfully terminate a process. Specifically, the facet invokes shutdown on its communicator and assumes that the application uses this event as a signal to commence its termination procedure. For example, an application typically uses a thread (often the main thread) to call the communicator operation waitForShutdown, which blocks the calling thread until the communicator is shut down or destroyed. After waitForShutdown returns, the calling thread can initiate a graceful shutdown of its process.

Replacing the Process Facet

You can replace the default Process facet if your application requires a different scheme for gracefully shutting itself down. To define your own facet, create a servant that implements the Ice::Process interface. As an example, the C++ servant definition shown below duplicates the functionality of the default Process facet:

class MyProcess final : public Ice::Process
{
public:
    MyProcess(Ice::CommunicatorPtr communicator) :
        _communicator{std::move(communicator)}
    {
    }

    void shutdown(const Ice::Current&) final
    {
        _communicator->shutdown();
    }

    void writeMessage(
        std::string message,
        std::int32_t fd,
        const Ice::Current&) final
    {
        switch (fd)
        {
            case 1:
            {
                cout << message << endl;
                break;
            }
            case 2:
            {
                cerr << message << endl;
                break;
            }
        }
    }

private:
    const Ice::CommunicatorPtr _communicator;
};

As you can see, the default implementation of shutdown simply shuts down the communicator, which initiates an orderly termination of the Ice runtime's server-side components and prevents object adapters from dispatching any new requests. You can add your own application-specific behavior to the shutdown method to ensure that your program terminates in a timely manner.

To avoid the risk of a race condition, the recommended strategy for replacing the Process facet is to delay creation of the administrative facets until after communicator initialization, so that your application has a chance to replace the facet:

# Delay admin object creation for admin object hosted in the Ice.Admin
# object adapter
Ice.Admin.DelayCreation=1

With Ice.Admin.DelayCreation enabled, the application can safely remove the default Process facet and install its own:

Ice::CommunicatorPtr communicator = ...;
communicator->removeAdminFacet("Process");
auto myProcessFacet = make_shared<MyProcess>(...);
communicator->addAdminFacet(myProcessFacet, "Process");

If you host the admin object in the Ice.Admin object adapter, the final step is to create the admin object by calling getAdmin on the communicator. And if you host the admin object in your own object adapter, the final set is to create the admin object with createAdmin.

Obtaining the Local Process Facet

We already showed how to obtain a proxy for a remote administrative facet, but suppose you want to interact with the facet in your local address space. The code below shows the necessary steps:

if (communicator.findAdminFacet("Process") is Ice.Process process)
{
    ...
}
// else, the facet is not enabled

Application Requirements for the Process Facet

The default implementation of the Process facet requires cooperation from an application in order to successfully terminate a process. Specifically, the facet invokes shutdown on its communicator and assumes that the application uses this event as a signal to commence its termination procedure. For example, an application typically uses a thread (often the main thread) to call the communicator operation waitForShutdown, which blocks the calling thread until the communicator is shut down or destroyed. After waitForShutdown returns, the calling thread can initiate a graceful shutdown of its process.

Replacing the Process Facet

You can replace the default Process facet if your application requires a different scheme for gracefully shutting itself down. To define your own facet, create a servant that implements the Ice::Process interface. As an example, the C# servant definition shown below duplicates the functionality of the default Process facet:

internal sealed class MyProcess : Ice.ProcessDisp_
{
    private readonly Ice.Communicator _communicator;

    public MyProcess(Ice.Communicator communicator) => _communicator = communicator;

    public override void shutdown(Ice.Current current) => _communicator.shutdown();

    public override void writeMessage(string message, int fd, Ice.Current current)
    {
        switch (fd)
        {
            case 1:
            {
                Console.Out.WriteLine(message);
                break;
            }
            case 2:
            {
                Console.Error.WriteLine(message);
                break;
            }
        }
    }
}

As you can see, the default implementation of shutdown simply shuts down the communicator, which initiates an orderly termination of the Ice runtime's server-side components and prevents object adapters from dispatching any new requests. You can add your own application-specific behavior to the shutdown method to ensure that your program terminates in a timely manner.

To avoid the risk of a race condition, the recommended strategy for replacing the Process facet is to delay creation of the administrative facets until after communicator initialization, so that your application has a chance to replace the facet:

# Delay admin object creation for admin object hosted in the Ice.Admin
# object adapter
Ice.Admin.DelayCreation=1

With Ice.Admin.DelayCreation enabled, the application can safely remove the default Process facet and install its own:

Ice.Communicator communicator = ...;
communicator.removeAdminFacet("Process");
var myProcessFacet = new MyProcess(...);
communicator.addAdminFacet(myProcessFacet, "Process");

If you host the admin object in the Ice.Admin object adapter, the final step is to create the admin object by calling getAdmin on the communicator. And if you host the admin object in your own object adapter, the final set is to create the admin object with createAdmin.

Obtaining the Local Process Facet

We already showed how to obtain a proxy for a remote administrative facet, but suppose you want to interact with the facet in your local address space. The code below shows the necessary steps:

com.zeroc.Ice.Object obj = communicator.findAdminFacet("Process");
if (obj != null) { // It's null when the facet is not enabled
    var process = (com.zeroc.Ice.Process)obj;
    ...
}

Application Requirements for the Process Facet

The default implementation of the Process facet requires cooperation from an application in order to successfully terminate a process. Specifically, the facet invokes shutdown on its communicator and assumes that the application uses this event as a signal to commence its termination procedure. For example, an application typically uses a thread (often the main thread) to call the communicator operation waitForShutdown, which blocks the calling thread until the communicator is shut down or destroyed. After waitForShutdown returns, the calling thread can initiate a graceful shutdown of its process.

Replacing the Process Facet

You can replace the default Process facet if your application requires a different scheme for gracefully shutting itself down. To define your own facet, create a servant that implements the Ice::Process interface. As an example, the Java servant definition shown below duplicates the functionality of the default Process facet:

class MyProcess implements com.zeroc.Ice.Process {
    private final com.zeroc.Ice.Communicator _communicator;

    public MyProcess(com.zeroc.Ice.Communicator communicator) {
        _communicator = communicator;
    }

    @Override
    public void shutdown(com.zeroc.Ice.Current current) {
        _communicator.shutdown();
    }

    @Override
    public void writeMessage(String message, int fd, com.zeroc.Ice.Current current) {
        switch (fd) {
            case 1 -> System.out.println(message);
            case 2 -> System.err.println(message);
        }
    }
}

As you can see, the default implementation of shutdown simply shuts down the communicator, which initiates an orderly termination of the Ice runtime's server-side components and prevents object adapters from dispatching any new requests. You can add your own application-specific behavior to the shutdown method to ensure that your program terminates in a timely manner.

To avoid the risk of a race condition, the recommended strategy for replacing the Process facet is to delay creation of the administrative facets until after communicator initialization, so that your application has a chance to replace the facet:

# Delay admin object creation for admin object hosted in the Ice.Admin
# object adapter
Ice.Admin.DelayCreation=1

With Ice.Admin.DelayCreation enabled, the application can safely remove the default Process facet and install its own:

Communicator communicator = ...;
communicator.removeAdminFacet("Process");
var myProcessFacet = new MyProcess(...);
communicator.addAdminFacet(myProcessFacet, "Process");

If you host the admin object in the Ice.Admin object adapter, the final step is to create the admin object by calling getAdmin on the communicator. And if you host the admin object in your own object adapter, the final set is to create the admin object with createAdmin.

Obtaining the Local Process Facet

We already showed how to obtain a proxy for a remote administrative facet, but suppose you want to interact with the facet in your local address space. The code below shows the necessary steps:

The built-in process facet servant is not exposed in the Python mapping; Python applications can access it only via its proxy.

Application Requirements for the Process Facet

The default implementation of the Process facet requires cooperation from an application in order to successfully terminate a process. Specifically, the facet invokes shutdown on its communicator and assumes that the application uses this event as a signal to commence its termination procedure. For example, an application typically uses a thread (often the main thread) to call the communicator operation waitForShutdown, which blocks the calling thread until the communicator is shut down or destroyed. After waitForShutdown returns, the calling thread can initiate a graceful shutdown of its process.

Replacing the Process Facet

You can replace the default Process facet if your application requires a different scheme for gracefully shutting itself down. To define your own facet, create a servant that implements the Ice::Process interface. As an example, the Python servant definition shown below duplicates the functionality of the default Process facet:

class MyProcess(Ice.Process):
    def __init__(self, communicator: Ice.Communicator):
        self._communicator = communicator

    def shutdown(self, current: Ice.Current) -> None:
        self._communicator.shutdown()

    def writeMessage(self, message: str, fd: int, current: Ice.Current) -> None:
        if fd == 1:
            print(message)
        elif fd == 2:
            print(message, file=sys.stderr)

As you can see, the default implementation of shutdown simply shuts down the communicator, which initiates an orderly termination of the Ice runtime's server-side components and prevents object adapters from dispatching any new requests. You can add your own application-specific behavior to the shutdown method to ensure that your program terminates in a timely manner.

To avoid the risk of a race condition, the recommended strategy for replacing the Process facet is to delay creation of the administrative facets until after communicator initialization, so that your application has a chance to replace the facet:

# Delay admin object creation for admin object hosted in the Ice.Admin
# object adapter
Ice.Admin.DelayCreation=1

With Ice.Admin.DelayCreation enabled, the application can safely remove the default Process facet and install its own:

communicator = ...
communicator.removeAdminFacet("Process")
myProcessFacet = MyProcess(...)
communicator.addAdminFacet(myProcessFacet, "Process")

If you host the admin object in the Ice.Admin object adapter, the final step is to create the admin object by calling getAdmin on the communicator. And if you host the admin object in your own object adapter, the final set is to create the admin object with createAdmin.

Obtaining the Local Process Facet

We already showed how to obtain a proxy for a remote administrative facet, but suppose you want to interact with the facet in your local address space. The code below shows the necessary steps:

if let process = communicator.findAdminFacet("Process") as? Process {
    ...
}

Application Requirements for the Process Facet

The default implementation of the Process facet requires cooperation from an application in order to successfully terminate a process. Specifically, the facet invokes shutdown on its communicator and assumes that the application uses this event as a signal to commence its termination procedure. For example, an application typically uses a thread (often the main thread) to call the communicator operation waitForShutdown, which blocks the calling thread until the communicator is shut down or destroyed. After waitForShutdown returns, the calling thread can initiate a graceful shutdown of its process.

Replacing the Process Facet

You can replace the default Process facet if your application requires a different scheme for gracefully shutting itself down. To define your own facet, create a servant that implements the Ice::Process interface. As an example, the Swift servant definition shown below duplicates the functionality of the default Process facet:

final class MyProcess: Ice.Process {
    private let communicator: Ice.Communicator

    init(communicator: Ice.Communicator) {
        self.communicator = communicator
    }

    func shutdown(current _: Ice.Current) {
        communicator.shutdown()
    }

    func writeMessage(message: String, fd: Int32, current _: Ice.Current) {
        switch fd {
        case 1:
            print(message)
        case 2:
            FileHandle.standardError.write(Data((message + "\n").utf8))
        default:
            break
        }
    }
}

As you can see, the default implementation of shutdown simply shuts down the communicator, which initiates an orderly termination of the Ice runtime's server-side components and prevents object adapters from dispatching any new requests. You can add your own application-specific behavior to the shutdown method to ensure that your program terminates in a timely manner.

To avoid the risk of a race condition, the recommended strategy for replacing the Process facet is to delay creation of the administrative facets until after communicator initialization, so that your application has a chance to replace the facet:

# Delay admin object creation for admin object hosted in the Ice.Admin
# object adapter
Ice.Admin.DelayCreation=1

With Ice.Admin.DelayCreation enabled, the application can safely remove the default Process facet and install its own:

let communicator = ...
try communicator.removeAdminFacet("Process")
try communicator.addAdminFacet(servant: MyProcess(...), facet: "Process")

If you host the admin object in the Ice.Admin object adapter, the final step is to create the admin object by calling getAdmin on the communicator. And if you host the admin object in your own object adapter, the final set is to create the admin object with createAdmin.