Service interrupt handler

This feature enables developers to respond appropriately to any events that interrupt the running of a service instance during execution of a task. It is applicable to all supported operating systems.

About service interrupt handling

A service interrupt is as any event that is propagated from the middleware to the service instance indicating an interruption has happened in a running task. Interruptions can arise when:
  • A session is killed
  • A session is suspended
  • A resource is reclaimed
  • A task is killed
  • An application is unregistered or disabled
  • A middleware component is not available

This feature allows interrupt handling to move from a polling model to an event-driven model. The polling model is still available for backward compatibility.

When a service implements the Service Interrupt handler, the service is informed as soon as the interrupt occurs. Service developers no longer need to have a separate monitoring thread for interrupts to determine when an interrupt has occurred.

Only task-level events are propagated to a running service instance. An interrupt is not delivered to a running service instance if no task is running (onInvoke is not called).

Once the onServiceInterrupt() handler is triggered, it is passed the current service context object. To get more details about the actual interrupt (for example, to retrieve the event and grace period in the interrupt handler), the service can call the getLastInterruptEvent method on the service context object.

Supported interrupts

The Service Interrupt handler can send the following interrupts to a service instance at any time:
Task killed interrupt
This interrupt is sent as a result of an administrative operation to kill a task or a session. When called, the onInvoke() handler is expected to return from its processing by the time the grace period expires. If the grace period expires with no reply from the service, the service is terminated.
  • C++: InterruptTaskKilled
  • Java™: InterruptEvent.TASK_KILLED
  • C# .NET: InterruptEventCode.TaskKilled
Task suspended interrupt
This interrupt is sent as a result of an administrative operation to suspend a session or when a resource running the service instance is being reclaimed. When called, the onInvoke() handler is expected to return from its processing by the time the grace period expires. If the grace period expires with no reply from the service, the service is terminated. If the onInvoke() handler successfully finishes before the grace period expires, the task is considered done.
  • C++: InterruptTaskSuspended
  • Java: InterruptEvent.TASK_SUSPENDED
  • C# .NET: InterruptEventCode.TaskSuspended

Error handling

Interrupts do not have any error handling associated with them. Any exception thrown while handling this method is ignored by the middleware. The middleware reports the exception to the service instance so that the service instance can take the necessary actions to handle the exception.

Service interrupt handling API

The following handlers are introduced to the service:
C++
virtual void onServiceInterrupt (ServiceContextPtr& serviceContext)
Java
public void onServiceInterrupt (ServiceContext serviceContext) throws SoamException
C# (.NET)
public override void OnServiceInterrupt(ServiceContext serviceContext)