Subscribing to Advisory Messages

To receive advisory messages, programs can create subscribers on a special endpoint named _advisoryEndpoint. (In each supported programming language, an API constant has the name of this endpoint as its value.)

Scope and Restrictions

Note: The realm object scopes the advisories that a subscriber can receive on the special advisory endpoint, _advisoryEndpoint. That is, a subscriber to this endpoint receives only those advisories produced by other objects in the same program and the same realm as the advisory subscriber.

It is illegal to create publishers on the special advisory endpoint.

Procedure

  1. Determine the set of advisory messages to receive.
  2. Determine the action of your program in response to each advisory message.
  3. Define message callbacks to process the advisory messages.

    For example, an advisory callback might respond by logging the content of the advisory, by notifying an administrator, or by exiting.

  4. Optional. Define content matchers.

    A subscriber may receive all advisory messages without distinguishing among them, or it may select a specific subset of advisory messages using a content matcher.

  5. Create subscribers on the special advisory endpoint.
  6. Create a special event queue, dedicated only to dispatching and processing advisory messages.

    This queue must never discard events.

  7. Code a special dispatch thread within your program, dedicated only to dispatching the advisory event queue. Ensure that this thread always receives sufficient CPU cycles in a timely fashion, even when other dispatch threads might be stuck.
  8. Add the advisory subscribers to the dedicated advisory event queue.
Related reference