INtime SDK Help
CreateRtMailbox
INtime SDK v7.1 > About INtime > INtime Kernel > Mailboxes > CreateRtMailbox

Creates a new mailbox and returns a handle for it. The mailbox type is determined by wMailboxFlags.

RTHANDLE CreateRtMailbox(
    WORD wMailboxFlags    // Mailbox creation flags
);

Parameters

wMailboxFlags
Specifies flags that control the creation of the mailbox. Possible values are described below. Values may be combined where appropriate.
OBJECT_MAILBOX This flag indicates that the mailbox is to be created to pass RT object handles. It is mutually exclusive with the DATA_MAILBOX flag. The depth of the mailbox may be specified by the MAILBOX_DEPTH(n) macro.
DATA_MAILBOX This flag indicates that the mailbox is to be created to pass up to 128-byte messages. In this case the depth of the mailbox is initially 3 messages.
FIFO_QUEUING This flag indicates that threads will be queued in First-In-First-Out order on this object.
PRIORITY_QUEUING This flag indicates that threads will be queued in priority order on this object.
MAILBOX_DEPTH(n) This macro determines the number of objects which can be queued in an object mailbox. It is ignored for data mailboxes. The value n must be at least 8, at most 60, and a multiple of 4.

Remarks

When you set up a mailbox to pass objects (not data) you can also set up a high-performance queue. This queue is a block of memory that stores objects waiting to be sent or received. It is permanently assigned to the mailbox, and the unused portion of the queue is unavailable for other uses. If the queue overflows, the Nucleus temporarily allocates another 200-object queue.

To get the best tradeoff between memory and performance, choose a size for your high-performance queue that is large enough for normal operations, and let the overflow queue handle unusual circumstances.

When you create a mailbox to pass data, you do not specify the size of the message queue. The OS automatically sets up a queue of 400 bytes.

Return Values

A handle for the mailbox object just created
Success
BAD_RTHANDLE
To determine the status, call GetLastRtError

Status

E_OK 0x0000
No exceptional conditions occurred.
E_MEM 0x0002
Creating a mailbox requires more available memory to the calling thread's process than currently exists.
E_LIMIT 0x0004
The calling thread's process reached its object limit.
E_SLOT 0x000C
You cannot create more RT objects because the GDT's slots are full.

Requirements

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/rtbase.h rt.h rt.lib

See Also

Mailbox system calls