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.

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

See Also

Mailbox system calls