Prioritization

The Default Prioritizer

Providing a Prioritizer

Chapter 8 - Advanced Notifier Usage 63

is vetoed. Thus, a common idiom is:

(void) notify_post_destroy(client, DESTROY CHECKING, NOTIFY_SAFE);

(void) notify_post_destroy(client, DESTROY_CLEANUP, NOTIFY_SAFE);

The order in which a particular client' s conditions are notified may be controlled by providing a

prioritizer

The default prioritizer makes its notifications in this order (any asynchronous or immediate notifications have already been sent):

o Interval timer notifications (ITIMER_REAL and then ITIMER_ VIRTUAL).

o Child process control notifications.

o Synchronous signal notifications by ascending signal numbers.

o Exception file descriptor activity notifications by ascending fd numbers.

o Handle client events by order in which received.

o Output file descriptor activity notifications by ascending fd nwnbers.

o Input file descriptor activity notifications by ascending fd nwnbers.

This section describes how a client can provide its own prioritizer.

Notify_func

notify_set_prioritizer_func(client, prioritizer_func) Notify_client client;

Notify_func prioritizer_func;

notify _set_priori tizer_func ( ) takes an opaque client handle and the function to call before any notifications are sent to client. The previous func-tion that would have been called is returned. If this function was never defined then the default prioritization function is returned. If the

priori tizer_func ( ) argument is NOTIFY_FUNC_NULL then no client prioritization is done for client and the default prioritizer is used.

The calling sequence of a prioritizer function is:

18 It is anticipated that this facility will be rarely used by clients and that a client will rely on the ordering provided by the default prioritizer.

sun

microsystems

Notify_value

prioritizer_func(client, nfd, ibits_ptr, obits_ptr,

ebits_ptr, nsig, sigbits_ptr, auto_sigbits_ptr, event_count_ptr, events, args)

Notify_client client;

fd_set *ibits_ptr, *obits_ptr, *ebits_ptr;

int nfd, nsig, *sigbits_ptr,

*auto_sigbits_ptr, *event_count_ptr;

Notify_event *events;

Notify_arg *args;

#define SIG_BIT(sig) (1 « «sig)-l»

in which client from notify _set_prioritizer_func ( ) are passed to pr ior i t i zer _ func ( ). In addition, all the notifications that the Notifier is planning on sending to client are described in the other parameters. This data reflects only data that client has expressed interest in by asking for

notification of these conditions.

nfd describes the maximwn nwnber of valid bits in the fd set structures¹⁹ pointed to by ibits_ptr, obits_ptr, and ebits_ptr. ibits_ptr points to a bit mask of those file descriptors with input pending for client;

similarly obits _ptr points to a bit mask of file descriptors with output com-pleted, and ebi ts _ptr points to a bit mask of file descriptors on which an exception occurred. ns ig describes the maximwn nwnber of valid bits in the arrays pointed to by sigbits_ptr and auto_sigbits_ptr.

sigbits_ptr is a bit mask of signals received for which client has a condi-tion registered; the S I G _BIT macro can be used to access the correct bit.

auto_sigbits_ptr is a bit mask of signals received that the Notifier is managing on behalf of client. event_count is the number of events in the array events. events is an array of pending client events and args is the parallel array of event argwnents.

The return value is one of NOTIFY DONE _- or NOTIFY IGNORED. _- These have their normal meanings:

o NOTIFY DONE - All of the conditions had notifications sent for them.

This implies that no further notifications should be sent to client this time around the notification loop. Unsent notifications are preserved for con-sideration the next time around the notification loop.

o NOTIFY IGNORED - A notification was not sent for one or more of the conditions, i.e., some notifications may have been sent, but not all. This implies that another prioritizer should try to send any remaining notifications to client.

19 With the increase past 32 of the maximum number of file descriptors under SunOS Release 4.0, the masks ofFD bits are no longer ,ints but a special structure, defined in <sys/types. h>.

sun

microsystems

Dispatching Events

Chapter 8 - Advanced Notifier Usage 65

From within a prioritization routine, the following functions are called to cause the specified notifications to be sent:

Notify_error

notify_event(client, event, arg) Notify_client client;

Notify_event event;

Notify_arg arg;

Notify_error

notify_input(client, fd) Notify_client client;

int fd;

Notify_error

notify_output(client, fd) Notify_client client;

int fd;

Notify_error

notify_exception(client, fd) Notify_client client;

int fd;

Notify_error

notify_itimer(client, which) Notify_client client;

int which;

Notify_error

notify_signal(client, signal) Notify_client client;

int signal;

Notify_error

notify_wait3(client)

Notify_client client;

The Notifier won't send any notifications that it wasn't planning on sending any-way, so one can't use these calls to drive clients programmatically. A return value of NOTIFY OK indicates that cl ient was sent the notification. A return value of NOTIFY_UNKNOWN_CLIENT indicates that client is not recognized by the N otifier and no notification was sent. A return value of

NOTIFY_NO_CONDITION indicates that client does not have the requested notification pending and no notification was sent.

A client may chose to replace the default prioritizer. Alternatively, a client's prioritizer may call the default prioritizer after sending only a few notifications.

Any notifications not explicitly sent by a client prioritizer will be sent by the default prioritizer (when called), in their normal turn. Once notified, a client will not receive a duplicate notification for the same event.

~~sun

Getting the Prioritizer