.TH osCreateMesgQueue 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osCreateMesgQueue, osSendMesg, osJamMesg, osRecvMesg \- messaging and synchronization facilities
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
void osCreateMesgQueue(OSMesgQueue \(**mq, OSMesg \(**msg, s32 count);
.sp .8v
s32 osSendMesg(OSMesgQueue \(**mq, OSMesg msg, s32 flag);
.sp .8v
s32 osJamMesg(OSMesgQueue \(**mq, OSMesg msg, s32 flag);
.sp .8v
s32 osRecvMesg(OSMesgQueue \(**mq, OSMesg \(**msg, s32 flag);
.Op
\f1
.fi
.SH DESCRIPTION
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
.IR osSetEventMesg (3P)
for a complete list of events.
.PP
The 
.I osCreateMesgQueue
call initializes a given OSMesgQueue structure
.I mq
to an empty state.
The
.I msg
argument points to a OSMesg array that is used for storing messages in this
queue and 
.I count
specifies the total number of messages the given queue can hold
(the size of the array).
.PP
The
.I osSendMesg
call copies the message
.I msg
to the end of the given message queue
.IR mq .
The
.I flag
argument specifies the blocking mode of this send operation.
If
.I flag
is set to
.I OS_MESG_BLOCK,
the routine blocks on a full message queue;
that is, the invoking thread yields the CPU until there is an
empty slot in the queue for writing.
This thread is enqueued onto a priority linked list associated with
the message queue behind other threads of the same priority.
The
.I osSendMesg
call will always return 0 for a blocking send call.
Setting
.I flag
to
.I OS_MESG_NO_BLOCK
allows the
.I osSendMesg
call to return immediately with a return value of -1 when
the message queue is full;
otherwise the message is delivered and the call returns with a return value
of 0.
Furthermore,
.I osSendMesg
call will resume the highest priority thread blocked in
.I osRecvMesg
waiting for the queue to become non empty, if indeed one is blocked.
.PP
The
.I osJamMesg
call works like
.I osSendMesg
except that the message
.I msg
is copied to the front of the given message queue
.IR mq.
This call may be used to deliver high priority messages.
.PP
The
.I osRecvMesg
call copies the first message in the message queue
.I mq
into the address specified by
.IR msg.
If a NULL
.IR msg
is passed to
.I 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 
.I flag
is set to
.I 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
.I osRecvMesg
call will always return 0 for a blocking receive call.
Setting
.I flag
to
.I OS_MESG_NOBLOCK
allows the
.I osRecvMesg
call to return immediately with a return value of -1 when
the message queue is empty;
otherwise the message is received and the call returns with a return value
of 0.
Finally,
.I osRecvMesg
call will resume the highest priority thread blocked in
.I osSendMesg
or
.I osJamMesg
waiting for a message queue slot to become available,
if one is in fact blocked.
.SH "SEE ALSO"
.IR osCreateThread (3P),
.IR osSetEventMesg (3P)