OSReceiveMessage

Syntax

#include <cafe/os.h>
    
BOOL OSReceiveMessage(OSMessageQueue* mq,
                      OSMessage*      msg,
                      s32             flags);

Parameters

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

Return Values

Returns TRUE if the message was retrieved without any issues. Returns FALSE if OS_MESSAGE_NOBLOCK was specified and the queue is empty.

Description

Extracts messages from the message queue. If any functions are currently blocked because of a full queue, they will be executed after this function. The sending threads execute in order of priority.

If flags is set to OS_MESSAGE_BLOCK and the queue is empty, the thread that called this function will be paused. The thread resumes after a 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 flags is set to OS_MESSAGE_NOBLOCK, 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.

NOTE:
The system message queue must be called at least once using the NOBLOCK flag.

Do Not Call From

Callbacks Do not call this function from any callback function.

See Also

OSInitMessageQueue
OSSendMessage

Revision History

2013/05/08 Automated cleanup pass.
2012/08/01 Cleanup pass.
2010/08/30 Initial version.


CONFIDENTIAL