1.3 eDirectory Event Priorities

The priority parameter of NWDSERegisterForEvent specifies the registered priority of a callback.The behavior of a callback must respond partly to its registered priority.

This section covers the following topics:

The priority flags determine the order in which handlers are notified when an event is generated. When an event is generated, the module reports the event to the Slot Table. Handlers are notified in the following order:

The following figure illustrates how the handlers are notified. It also traces which thread is used to process the handler’s callback function.

Event Slot Table

The graphic shows the thread paths for three events. To simplify the graphic, each event has handlers registered for only one priority. The dots (·) indicate the beginning of a thread, or at least where the thread’s processing starts as it enters the eDirectory event system.

See Also

1.3.1 EP_INLINE

The EP_INLINE priority provides synchronous pre-event reporting, as follows:

  • The callback can determine whether or not the event is allowable. If the callback returns a nonzero value, the transaction is aborted, and the return value of the callback is returned to the client.
  • The client waits for a response while the callback processes. If the callback takes too long, the client could time out. Callbacks need to return as quickly as possible.
  • The callback cannot call any of the NWDS functions because the local database is locked. In addition, the only function it can use from eDirectory Event is NWDSEConvertEntryName.
  • The callback can sleep (normally only to allocate memory).
  • This priority faces the most difficult issues when using chained event handlers. You cannot assume that an eDirectory event will complete if your callback returns zero. This is because the next callback in the chain could abort the transaction. To verify that changes occurred, register a callback for the EP_JOURNAL or EP_WORK priorities.

See Also

1.3.2 EP_JOURNAL

The EP_JOURNAL priority provides synchronous post-event reporting, as follows:

  • Synchronous post-event reporting because event information is stored in a journal queue that records the events in the order they occurred.
  • A single thread services all of the callbacks for the events, so the callback’s execution time should be minimized. (The callback can determine if data should be used If it should be used, it can store the data in a list that another thread processes.)
  • If multiple callbacks are registered for the same event, the current callback must be processed before the next callback is called.
  • The callback can sleep.
  • The callback can use any of the NWDS and NWDSE functions.

IMPORTANT:While inside this callback, use discretion in calling NWDS functions that create more eDirectory events. This is a closed loop where the growth of the journal queue could be uncontrollable.

See Also

1.3.3 EP_WORK

The EP_WORK priority provides asynchronous postevent reporting, as follows:

  • The events are reported after they have occurred, but not necessarily in the order that they occurred. They are reported only after all of the event’s callbacks registered for the EP_JOURNAL priority have completed.
  • Each callback is run on a separate thread. This frees the event handler from the time constraints of the other two priorities.
  • The callback can use any of the NWDS and NWDSE functions.
  • The callback can sleep.
  • Time is not a critical issue.

See Also

1.3.4 Priority 0

For handlers registered for priority 0, the thread that generates the event is used to process all the handler callback functions. When they are finished processing, the thread returns to the module that generated the event. Since the same thread is used to process all the callback functions, callbacks need to return as quickly as possible.

Because the thread that generates the event is the same thread that processes the handlers’ callback functions, the callback functions can influence the outcome of the event. However, the last handler called has the final say. The value that is reported by the last handler is used for handlers that have registered for the other priorities and is returned the module that generated the event.

If more than one handler registers for priority 0, the handler cannot specify its position in the list. Handlers are added in the order they register. However, one handler can register to be the auditor handler (DSHF_AUDIT) with a notify flag. This places this handler last in the list and allows the handler’s callback function to have the final say in whether the event fails or succeeds. Only one handler can register as the auditor handler.

See Also

1.3.5 Priority 1

For handlers registered for priority 1, the thread that generates the event reports the event to the eDirectory Event Slot Table and immediately returns to the module that generated the event. The Slot Table then assigns a different thread to process all the callback functions registered for priority 1. Since the same thread is used to process all the callback functions, callbacks need to return as quickly as possible.

See Also

1.3.6 Priority 2

For handlers registered for priority 2, the thread that generates the event reports the event to the Slot Table and immediately returns to the module that generated the event. The eDirectory Event Slot Table then assigns a different thread to each registered handler. Since each callback function has its own thread, the callback function can be scheduled to do work that is time consuming. The results of the callbacks are asynchronous because the finishing order is indeterminate.

Each callback thread consumes a service process that is a limited resource on NetWare.

See Also