On this page:
Object Adapter State Transitions
An object adapter has a number of processing states:
- Holding
In this state, any incoming requests for the adapter are held, that is, not dispatched to servants.
For TCP/IP (and other stream-oriented protocols), the server-side run time stops reading from the corresponding transport endpoint while the adapter is in the holding state. In addition, it also does not accept incoming connection requests from clients. This means that if a client sends a request to an adapter that is in the holding state, the client eventually receives aTimeoutException
orConnectTimeoutException
(unless the adapter is placed into the active state before the timer expires).
For UDP, client requests that arrive at an adapter that is in the holding state are thrown away.
Immediately after creation of an adapter, the adapter is in the holding state. This means that requests are not dispatched until you place the adapter into the active state.
Note that bidirectional adapters cannot be placed into the holding state. If you callhold
on a bidirectional adapter, the call does nothing.
- Active
In this state, the adapter accepts incoming requests and dispatches them to servants. A newly-created adapter is initially in the holding state. The adapter begins dispatching requests as soon as you place it into the active state.
You can transition between the active and the holding state as many times as you wish.
Note that bidirectional adapters need not be activated. Further, calls to collocated servants (that is, to servants that are activated in the communicator that created the proxy) succeed even if the adapter is not activated, unless you have disabled collocation optimization.
- Inactive
In this state, the adapter has conceptually been destroyed (or is in the process of being destroyed). Deactivating an adapter destroys all transport endpoints that are associated with the adapter. Requests that are executing at the time the adapter is placed into the inactive state are allowed to complete, but no new requests are accepted. (New requests are rejected with an exception). Any attempt to use a deactivated object adapter results in anObjectAdapterDeactivatedException
.
Changing Object Adapter States
The ObjectAdapter
interface offers operations that allow you to change the adapter state, as well as to wait for a state change to be complete:
module Ice { local interface ObjectAdapter { // ... void activate(); void hold(); void waitForHold(); void deactivate(); void waitForDeactivate(); void isDeactivated(); void destroy(); // ... }; };
The operations behave as follows:
activate
Theactivate
operation places the adapter into the active state. Activating an adapter that is already active has no effect. The Ice run time starts dispatching requests to servants for the adapter as soon asactivate
is called.
hold
Thehold
operation places the adapter into the holding state. Requests that arrive after callinghold
are held as described above. Requests that are in progress at the timehold
is called are allowed to complete normally. Note thathold
returns immediately without waiting for currently executing requests to complete.
waitForHold
ThewaitForHold
operation suspends the calling thread until the adapter has completed its transition to the holding state, that is, until all currently executing requests have finished. You can callwaitForHold
from multiple threads, and you can callwaitForHold
while the adapter is in the active state. If you callwaitForHold
on an adapter that is already in the holding state,waitForHold
returns immediately.
deactivate
Thedeactivate
operation initiates deactivation of the adapter: requests that arrive after callingdeactivate
are rejected, but currently executing requests are allowed to complete. Once all requests have completed, the adapter enters the inactive state. Note thatdeactivate
returns immediately without waiting for the currently executing requests to complete. A deactivated adapter cannot be reactivated; you can create a new adapter with the same name, but only after callingdestroy
on the existing adapter. Any attempt to use a deactivated object adapter results in anObjectAdapterDeactivatedException
.
waitForDeactivate{
ThewaitForDeactivate
operation suspends the calling thread until the adapter has completed its transition to the inactive state, that is, until all currently executing requests have completed. You can callwaitForDeactivate
from multiple threads, and you can callwaitForDeactivate
while the adapter is in the active or holding state. CallingwaitForDeactivate
on an adapter that is in the inactive state does nothing and returns immediately.
isDeactivated
TheisDeactivated
operation returns true ifdeactivate
has been invoked on the adapter. A return value of true does not necessarily indicate that the adapter has fully transitioned to the inactive state, only that it has begun this transition. Applications that need to know when deactivation is completed can usewaitForDeactivate
.
destroy
Thedestroy
operation deactivates the adapter and releases all of its resources. Internally,destroy
invokesdeactivate
followed bywaitForDeactivate
, therefore the operation blocks until all currently executing requests have completed. Furthermore, any servants associated with the adapter are destroyed, all transport endpoints are closed, and the adapter's name becomes available for reuse.
Destroying a communicator implicitly destroys all of its object adapters. Invokingdestroy
on an adapter is only necessary when you need to ensure that its resources are released prior to the destruction of its communicator.
Placing an adapter into the holding state is useful, for example, if you need to make state changes in the server that require the server (or a group of servants) to be idle. For example, you could place the implementation of your servants into a dynamic library and upgrade the implementation by loading a newer version of the library at run time without having to shut down the server.
Similarly, waiting for an adapter to complete its transition to the inactive state is useful if your server needs to perform some final clean-up work that cannot be carried out until all executing requests have completed.
Note that you can create an object adapter with the same name as a previous object adapter, but only once destroy
on the previous adapter has completed.