INtime SDK Help
knCreateRtMailbox
INtime SDK v7 > About INtime > INtime Kernel > Mailboxes > knCreateRtMailbox

Creates a low-level mailbox with the given specifications.

KNHANDLE knCreateRtMailbox(
    KNPTR lpMailboxArea,
    DWORD cbMessageSize,
    DWORD dwQueueLength,
    DWORD dwKnMailboxFlags
);

Parameters

lpMailboxArea
Pointer to the area where the mailbox is to be created. For better performance, align this area on a 4-byte boundary. The size of this area must be:

KN_MAILBOX_SIZE + (cbMessageSize + KN_MAILBOX_MSG_OVERHEAD) * dwQueueLength where:
KN_MAILBOX_SIZE The number of bytes required for a mailbox object, excluding the message queue.
KN_MAILBOX_MSG_OVERHEAD The number of bytes of overhead for each message in the message queue of a mailbox.
cbMessageSize
Maximum size in bytes of the messages to be exchanged through this mailbox. Never send messages larger than the maximum message size specified for the mailbox; if you do, the results are unpredictable. Keep messages as small as possible. Transferring large messages can degrade the interrupt latency of the system.
dwQueueLength
Maximum number of messages that the mailbox can store.

If you set KN_RESERVE_PRIORITY_DATA, then 1 is automatically taken away from dwQueueLength. Add 1 to dwQueueLength to specify that 1 slot in the mailbox queue is reserved for a high-priority message when you set KN_RESERVE_PRIORITY_DATA. The reserved slot ensures that at least 1 high-priority message is accepted even if the mailbox queue is full. When a high-priority message arrives, if the message queue is full the RT kernel puts the high-priority message into the reserved slot. If that reserved slot is also taken, an E_KN_LIMIT_EXCEEDED status code returns. This is the same status that returns when a non-priority message cannot be sent because the mailbox queue is full.

When the kernel assigns messages to the mailbox, it assigns them in a circular fashion, assuming that the number of message slots is equal to dwQueueLength and the size of each message is equal to cbMessageSize. Even if the number of messages queued at the mailbox never reaches dwQueueLength, the circular queuing means that all the memory allocated for messages will be accessed at one time or another. The amount of memory you assign to the mailbox must match the values you specify for cbMessageSize and dwQueueLength.

dwKnMailboxFlags
Type of mailbox to be created. Values may be combined.
KN_EXCH_TYPE_MASK Masks the queuing strategy field. Choose one of the following:
  • KN_FIFO_QUEUING
    Threads are queued in the order that they arrive at the mailbox.
  • KN_PRIORITY_QUEUING
    Threads are queued based on their thread priority.
KN_RESERVE_PRIORITY_DATA_MASK Specifies whether the mailbox queue has a slot reserved for a high-priority message. Choose one of the following:
  • KN_DONT_RESERVE_PRIORITY_DATA
    Do not reserve a slot for a high-priority message.
  • KN_RESERVE_PRIORITY_DATA
    Reserve a slot for a high-priority message.

Note: KN_DONT_RESERVE_PRIORITY_DATA and KN_RESERVE_PRIORITY_DATA are mutually exclusive.

Remarks

The RT kernel tries to place high-priority messages ahead of all other messages in the regular queue. If the message queue is full, the kernel puts the high-priority message into the reserved slot (if you specified KN_RESERVE_PRIORITY_DATA).

The purpose of the reserved slot is to ensure at least 1 high-priority message is accepted even when the mailbox queue is full.

Although this call is non-scheduling, it is not recommended for use by interrupt handlers.

Note: From INtime version 6.2, for performance reasons, the area for each low-level semaphore or mailbox in a process is also mapped into common virtual memory. The default maximum number of pages reserved for low-level objects is 256. Low-level objects which share a page consume only one mapping between them. knCreateRtMailbox will fail and return a value of 0xffffffff if the number of mappings is exceeded.

Return Values

Success: the low-level handle for the newly-created mailbox.
Failure: the value 0xffffffff is returned if the lpMailboxArea pointer is not valid, or if the maximum number of mappings has been exceeded.

Requirements

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

See Also

Mailbox system calls