OSReceiveMessage

Syntax

#include <revolution/os.h>

BOOL OSReceiveMessage(
    OSMessageQueue* mq, 
    OSMessage*      msg, 
    s32             flags);

Arguments

*`mq`*	Pointer to message queue.
msg	Pointer to the message being received.
flags	If `OS_MESSAGE_BLOCK` is set, the `OSReceiveMessage` function blocks empty queues. When `OS_MESSAGE_NOBLOCK` is set, the `OSReceiveMessage` function immediately returns whether or not the queue is empty.

Return Values

Returns TRUE if the message was extracted without any problems.

Returns FALSE if OS_MESSAGE_NOBLOCK was specified and the queue is empty.

Description

Extracts messages from the message queue. With this function, you can execute any waiting threads to send a message to the queue. The sending threads execute in order of priority.

When OS_MESSAGE_BLOCK is set in flags, 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. Other receiving threads with a higher priority are executed first so be aware of when messages are removed. If the message queue is empty when this thread is executed, it will pause again until another message is sent to the queue.

If OS_MESSAGE_NOBLOCK is set in flags, the process immediately returns to the calling thread. If the queue is not empty, TRUE is returned. If it is empty, FALSE is returned.

Revision History

2006/03/01 Initial version.