iofunc_notify_trigger(), iofunc_notify_trigger_strict()

Arguments:

ctp

(iofunc_notify_trigger_strict() only) A pointer to a resmgr_context_t structure that the resource-manager library uses to pass context information between functions. This argument can be NULL to notify all clients that match, or a current ctp to notify only on the file descriptor of the current client.

nop

An array of three iofunc_notify_t structures that represent (in order), the input, output, and out-of-band notification lists whose entries you want to examine; for information about this structure, see the documentation for iofunc_notify().

count

The count that you want to compare to the trigger value for the event.

index

The index into the nop array that you want to check; one of the following:

• IOFUNC_NOTIFY_INPUT
• IOFUNC_NOTIFY_OUTPUT
• IOFUNC_NOTIFY_OBAND

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The iofunc_notify_trigger() function examines all entries given in the list maintained at nop[index] to see if each corresponding event should be delivered. If the specified count is greater than or equal to the trigger count for the particular notification list element, this function calls MsgDeliverEvent() to deliver the event to the client whose rcvid is stored in that list element, and the element is disarmed.

The iofunc_notify_trigger_strict() function is similar, except that only notifications armed via the file descriptor in the client that maps to the ctp argument are notified. The strict variant is useful when a duplicated file descriptor is closed, and only clients blocked on that descriptor are required to wake up and notice (EBADF on subsequent read or write). Calling this function with a ctp of NULL provides the same behavior as iofunc_notify_trigger().

A resource manager generally calls iofunc_notify_trigger_strict() in a close_dup callout to unblock any client poll() calls that are waiting on a file descriptor that's been closed. You should call it three times with a count value of INT_MAX, the ctp passed to the close_dup callout, and an index of IOFUNC_NOTIFY_INPUT, IOFUNC_NOTIFY_OUTPUT, and IOFUNC_NOTIFY_OBAND.

Within each notification list element is a sigevent structure describing the event to be delivered. If the client specified a code (i.e., the sigev_code member of sigevent) of SI_NOTIFY, then the value that they specified (i.e., the sigev_value member) has the top three bits ORed with the reason for the trigger, as in the following table:

index = IOFUNC_NOTIFY_INPUT

0x10000000, or _NOTIFY_COND_INPUT

index = IOFUNC_NOTIFY_OUTPUT

0x20000000, or _NOTIFY_COND_OUTPUT

index = IOFUNC_NOTIFY_OBAND

0x40000000, or _NOTIFY_COND_OBAND

If the client has specified a code of something other than SI_NOTIFY then this routine doesn't modify the value member in any way.

The sys/iofunc.h file also defines the IOFUNC_NOTIFY_INPUT_CHECK(), IOFUNC_NOTIFY_OUTPUT_CHECK(), and IOFUNC_NOTIFY_OBAND_CHECK() macros, which you can use to see if there are enough bytes in the lists to make it worthwhile to call iofunc_notify_trigger() to notify clients about:

#define IOFUNC_NOTIFY_INPUT_CHECK(__nop, __cnt, __tran)	...
#define IOFUNC_NOTIFY_OUTPUT_CHECK(__nop, __cnt) ...
#define IOFUNC_NOTIFY_OBAND_CHECK(__nop, __cnt, __tran)	...

The arguments are:

__nop

An array of three iofunc_notify_t structures that represent (in order), the input, output, and out-of-band notification lists whose entries you want to examine.

__cnt

The number of elements present in the corresponding queue (input, output, or out-of-band) to compare to the trigger value. The trigger value is provided by iofunc_notify() and specifies the number of elements that need to be present to trigger an event.

__tran

(IOFUNC_NOTIFY_INPUT_CHECK() and IOFUNC_NOTIFY_OBAND_CHECK() only) Nonzero if you want to arm the trigger when the list makes the transition from empty to nonempty. (For example, mq_notify() does this.)

Examples:

See Writing a Resource Manager

Classification:

QNX OS

Caveats

To ensure thread safety, lock the underlying object before calling this function. This object is usually an iofunc_attr_t structure; lock it by calling iofunc_attr_lock().