|Home > Iris APIs > Instance registry, instance discovery, and interface discovery > Unregistering instances|
instanceRegistry_unregisterInstance() unregisters an instance from the instance registry. It undoes all the effects of
When this function returns, the instance is no longer visible in
instanceRegistry_getList(). Other functions that receive an
instId argument fail with
E_unknown_instance_id if they are called with an unregistered
instanceRegistry_unregisterInstance(instId) and waiting for its
response is the only way of making sure the
IrisInterface of the instance with
instId is no longer in use.
Side effects of unregistering an instance:
instanceRegistry_unregisterInstance()automatically destroys all event streams that are sent to instance
. That is, event streams that were created with
The following constraints apply when unregistering instances:
IrisInterfacecan send the
Constraints on ongoing communication during unregistering:
instanceRegistry_unregisterInstance()request, the instance can call functions normally, and it must accept function call responses and respond to function calls normally.
instanceRegistry_unregisterInstance()request and before receiving a response to the request, the instance must not call any functions. It must accept function call responses and respond to function calls normally.
instanceRegistry_unregisterInstance()request, the instance must not call any functions. It can assume that
IrisInterfaceinterface will not be called after this point. It can destroy itself and the
IrisInterfaceafter this point.
instIdthat they no longer know about must return
instId. They either receive an OK response, or an error response from the destination instance or from a message-routing instance, for example the GlobalInstance. If the instance no longer exists, they receive an
E_unknown_instance_iderror. This is normal behavior and must not cause any side effects, for example closing the simulation. The caller is responsible for handling this error in a suitable way. It must assume that the
instIdinstance no longer exists.
If an instance fails to call
before destroying itself:
IrisInterfaceinterface, this is considered to be as severe a programming error as using a freed C++ object, and is explicitly forbidden.
If the instance is out-of-process, that is, connected using a TCP socket or any other mechanism, this is considered normal behavior. For example, this might happen if the remote process crashes or the TCP connection closes from the remote side. The message-routing instance that provided the connection is able to detect such a loss of connection. It must then:
instanceRegistry_unregisterInstance()into the rest of the system.
E_unknown_instance_iderror responses to all pending function calls that it is handling for the instance that was destroyed.