About synchronicity

With respect to the Application Event System (AES), "synchronicity" refers to the ability or inability of event handlers to run independently from other event handlers. Application events are synchronous when they must execute their handlers in a specific order. Application events are asynchronous when they can execute their handlers independently of other handlers.

A synchronous event handler is one that must be completed before the system continues to the next event handler in a sequence. For the entire application event to be handled successfully, all synchronous handlers in the sequence must complete successfully. The exception to this rule is that, if one event handler fails, other than for an illegal operation, and the system is set to ignore failures for that handler, the system can continue to the next synchronous event handler. Otherwise, the system returns a failure error, and no more event handlers in the sequence execute.

By contrast, an asynchronous event handler runs independently of other event handlers.

Synchronous events

Unless the application event is designed to suspend, the expectation is that the application event is completed synchronously. Therefore, synchronous event handlers execute in sequence in the same thread that generated it and block that thread until they are all executed or until a handler exits with a failure status.

Application events are synchronous when they are generated by:

  • Framework events
  • Calling the FireApplicationEvent() .NET method with the Synchronous parameter set to True
  • Using a form event handler with a Generate Application Event response type and the Synchronous option selected
  • Using a Generate Event event action type with the Synchronous parameter set to True

Asynchronous events

An asynchronous event runs in a different thread than the one that posted it, usually on an Application Server. In this case, the application event does not block the generating thread and runs independently of it. As soon as an acknowledgment is received that the event was successfully queued, the thread that generated the application event continues.

Application events are asynchronous when they are generated by:

  • Calling the FireApplicationEvent() .NET method with the Synchronous parameter set to False
  • Calling the dbo.FireEventSp or dbo.PostEventSp stored procedure
  • Using a form event handler with a Generate Application Event response type and the Synchronous option cleared
  • Using a Generate Event event action type with the Synchronous parameter set to False

Event handlers

Event handlers can be designated as synchronous or asynchronous at the time they are created, using the Synchronous check box on the Event Handlers form.

Any event, either synchronous or asynchronous, can execute an asynchronous event handler when execution reaches an event handler designated as an asynchronous event handler; that is, one for which the Synchronous check box is cleared. At this point:

  • The system sends the asynchronous event handler to the event handler queue.
    Note: The system performs queueing by means of the PostEventHandlerSp stored procedure, to which it passes the configuration name from the event state.
  • If queueing was successful, the application event's thread continues to the next event handler or, if no subsequent handlers are defined, completes the event.
  • If queueing was unsuccessful, the application event stops with a Fail condition.