N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

   

osRecvMesg

Format
#include <ultra64.h>

s32 osRecvMesg(OSMesgQueue *mq,
   OSMesg *msg, s32 flag);
What These Functions Do
The osCreateMesgQueue, osSendMesg, osJamMesg, and osRecvMesg functions are messaging and synchronization facilities.

Message queues provide a highly flexible communication and synchronization mechanism. The facilities are useful among threads, as well as between threads and events (primarily interrupts). See osSetEventMesg for a complete list of events.

The osRecvMesg call copies the first message in the message queue (mq) into the address specified by the msg argument. If a NULL msg is passed to osRecvMesg, the message in the queue is discarded. This is useful in cases where you don't care about the value of the message, only the fact that a synchronization event occurred. If the flag argument is set to OS_MESG_BLOCK, the routine blocks on an empty message queue; that is, the current running thread yields the CPU until there is a message available for reading in the queue. This thread is enqueued onto a priority-linked list associated with the message queue behind other threads of the same priority. The osRecvMesg call always returns 0 for a blocking receive call. Setting the flag argument to OS_MESG_NOBLOCK allows the osRecvMesg call to return immediately with a return value of -1 when the message queue is empty. If the message queue is not empty, the message is received and the call returns with a return value of 0. Then the osRecvMesg call resumes the highest priority thread blocked in the osSendMesg or osJamMesg message queue that is waiting for a message queue slot to become available, if one is in fact blocked.

See Also
osCreateMesgQueue
osSendMesg
osJamMesg
osCreateThread
osSetEventMesg



Nintendo® Confidential

Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.


Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated January 1998