NAME

mq_notify – notify thread that a message is available on a queue

See the notes section – contact the factory to use this function.

SYNOPSIS

#include <mqueue.h>

int mq_notify(mqd_t mqdes, const struct sigevent *notification );

struct sigevent {

int sigev_notify /* notification type */

int sigev_signo; /* signal number */

union sigval sigev_value; /* signal value */

};

union sigval {

int sival_int; /* integer value */

void *sival_ptr; /* pointer value */

};

DESCRIPTION

mq_notify() provides an asynchronous mechanism for threads to receive notice that messages are available in a message queue, rather than synchronously blocking (waiting) in mq_receive().

If notification is not NULL, this function registers the calling thread to be notified of message arrival at an empty message queue associated with the message queue descriptor, The notification specified by notification will be sent to the calling thread when the message queue becomes non-empty. At any time, only one thread may be registered for notification by a specific message queue. Also, if the calling thread or any other thread has already registered for notification of message arrival at the specified message queue, subsequent attempts to register for that message queue will fail.

When the notification is sent to the registered thread, its registration is removed. The message queue is then be available for registration.

If a thread has registered for notification of message arrival at a message queue and another thread is blocked in mq_receive() waiting to receive a message when a message arrives at the queue, the arriving message will be received by the appropriate mq_receive(), and no notification will be sent to the registered thread. The resulting behavior is as if the message queue remains empty, and this notification will not be sent until the next arrival of a message at this queue.

A thread which has registered for notification receives notification via the events associated with mr_receive(), and mq_sigrecv() if these calls are used. sigev_signo in sigevent is used to provide the event number the thread will receive if the message arrives. This event will occur when the thread is in any state and will be received by the thread only upon a call to mr_sigrecv() or mr_receive().

Any notification results in registration being removed. Registration is also removed if the calling thread either closes the message queue or exits.

RETURN VALUES

Upon successful completion, mq_notify() returns 0 ; otherwise, it returns a value of -1 and sets errno to indicate the error condition.

ERRORS

EBADF

mqdes is not a valid message queue descriptor.

EBUSY

A thread is already registered for notification by the message queue.

ENOSYS

mq_notify() is not supported by this implementation.

SEE ALSO

mq_close(), mq_open(), mq_receive(), mq_send()

NOTES

This function currently returns -1 and sets errno to ENOSYS.