OS_ReceiveMessage

C Specification

#include <nitro/os.h>
BOOL OS_ReceiveMessage(
OSMessageQueue*   mq,
OSMessage*        msg,
s32               flag );
  

Arguments

mq Pointer to the message queue
msg Received message
flag When OS_MESSAGE_BLOCK is set, the OS_ReceiveMessage function blocks empty queues. When OS_MESSAGE_NOBLOCK is set, the OS_ReceiveMessage function immediately returns whether or not the queue is empty.

Return Values

Returns TRUE if the message was removed without any problems. If OS_MESSAGE_NOBLOCK was specified and the queue was empty, FALSE is returned.

Description

Removes a message from the message queue This function also makes it possible to execute any thread waiting to send a message to the queue. The transmission threads execute in order of priority.

If OS_MESSAGE_BLOCK is set up in flag, the thread that called this function will be paused if the queue is empty. The thread resumes once the message is sent to the queue. If another receiving thread with a higher priority is present, those threads are executed first so be aware of the point at which messages are removed. If the message queue is empty when this thread is executed, it will be paused again until another message is sent to the queue.

If OS_MESSAGE_NOBLOCK is set up in flag, the process immediately returns to the thread that was called. If the queue is not empty, TRUE is returned. If it is empty, FALSE is returned.

See Also

OS_InitMessageQueue, OS_SendMessage, OS_JamMessage, OS_ReadMessage

Revision History

03/12/2004 Added OS_ReadMessage to See Also
12/01/2003 Initial version