5.20.3 Unregistering instances

instanceRegistry_unregisterInstance() unregisters an instance from the instance registry. It undoes all the effects of instanceRegistry_registerInstance().

When instanceRegistry_unregisterInstance() returns, the instance is no longer visible to instanceRegistry_getList(). Functions that receive an instId argument fail with E_unknown_instance_id if they are called with an unregistered instId.

Calling instanceRegistry_unregisterInstance(instId) and waiting for its response is the only way to make sure the IrisInterface of the instance with instId is no longer in use.

Side effects of unregistering an instance:

  • Unregistering instance X using instanceRegistry_unregisterInstance() automatically destroys all event streams that are sent to instance X. That is, event streams that were created with eventStream_create(ecInstId=X).
  • Unregistering an instance does not affect any breakpoints that the instance has set.

The following constraints apply when unregistering instances:

  • Instances must unregister themselves as late as possible, in other words just before or during destruction, as long as an IrisInterface can send the instanceRegistry_unregisterInstance() function call.
  • Constraints on communication during unregistering:

    • Before sending the instanceRegistry_unregisterInstance() request, the instance can call functions normally, and it must accept function call responses and respond to function calls normally.
    • After sending the 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.
    • After receiving the response to the instanceRegistry_unregisterInstance() request, the instance must not call any functions. It must assume that irisHandleMessage() on its IrisInterface interface will not be called after this point. It can destroy itself and the IrisInterface after this point.
  • Instances that receive a function call for an unregistered instId must return E_unknown_instance_id.
  • At any time, other instances can call functions for a specific 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_id error. 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.

If an instance fails to call instanceRegistry_unregisterInstance(instId) before destroying itself:

  • If the instance is in-process, that is, connected using the C++ IrisInterface interface, 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:

    • Synthesize a call to instanceRegistry_unregisterInstance() into the rest of the system.
    • Send E_unknown_instance_id error responses to all pending function calls that it is handling for the instance that was destroyed.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.