5 Mailbox Services

In This Chapter

We describe the Mailbox kernel services in detail. The Mailbox kernel services provide data passing between the calling task and other tasks through mailboxes.

KS_CloseMbox ... 166 KS_DefMboxName ... 168 KS_DefMboxProp... 170 KS_DefMboxSema ... 172 KS_GetMboxClassProp ... 176 KS_GetMboxName ... 178 KS_GetMboxProp... 180 KS_GetMboxSema ... 182 INIT_MboxClassProp... 184 KS_LookupMbox ... 186 KS_OpenMbox ... 188 KS_UseMbox ...191

KS_CloseMbox

KS_CloseMbox

End the use of a dynamic mailbox.

Synopsis

KSRC KS_CloseMbox (MBOX mbox)

Input

Description

^The KS_CloseMbox kernel service ends the Current Task’s use of the dynamic mailbox specified in mbox. When closing the mailbox, the service detaches the caller’s use of it. If the caller is the last user of the mailbox, the service releases the mailbox to the free pool of dynamic mailboxes for reuse. If there is at least one other task still using the mailbox, the service does not release the mailbox to the free pool but completes successfully.

Be careful when closing a mailbox on which one or more tasks may be waiting. Closing the mailbox may cause waiters to be lost.

However, you can avoid this problem if each task that uses the mailbox makes a KS_UseMbox call before it begins using the mailbox and then makes a KS_CloseMbox call when it is done using the mailbox.

Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if the service is successful.

` RC_STATIC_OBJECT if the specified mailbox is not dynamic.

` RC_OBJECT_NOT_INUSE if the specified mailbox does not correspond to an active dynamic mailbox.

` RC_OBJECT_INUSE if the Current Task’s use of the specified mailbox is closed but the mailbox remains open for use by other tasks.

mbox The handle of the mailbox.

KS_CloseMbox

Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.

Error

This service may generate the following fatal error code:

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

Example

In Example 5-1, the Current Task waits on a signal from another task indicating that it is time to close a dynamic mailbox. The handle of the dynamic semaphore associated with the signal is specified in dynsema. The handle of the dynamic mailbox is specified in dynmbox. When the signal is received, the Current Task closes the dynamic mailbox even if there are other users.

Example 5-1. Close Mailbox

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

MBOX dynmbox;

SEMA dynsema;

KSRC ksrc;

KS_TestSemaW (dynsema); /* wait for signal */

/* then close the mailbox */

if ((ksrc = KS_CloseMbox (dynmbox)) != RC_GOOD) {

/* okay if other users exist */

if (ksrc != RC_OBJECT_INUSE) {

... mailbox cannot be closed. Deal with it here.

} }

/* Otherwise, mailbox closed and released to the */

/* free pool */

... Continue

KS_DefMboxName

KS_DefMboxName

Define the name of a previously opened dynamic mailbox.

Synopsis

KSRC KS_DefMboxName (MBOX mbox, const char *pname)

Inputs

Description

^The KS_DefMboxName kernel service names or renames the open dynamic mailbox specified in mbox. The service uses the null-terminated string pointed to by pname for the mailbox’s new name.

Static mailboxes cannot be named or renamed under program control.

Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.

This service does not check for duplicate task names.

Output

This service returns a ^KSRC value as follows:

` RC_GOOD if the service completes successfully.

` RC_STATIC_OBJECT if the mailbox being named is static.

` RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Mailbox class is not enabled.

` RC_OBJECT_NOT_INUSE if the specified mailbox does not correspond to an active dynamic mailbox.

Error

This service may generate the following fatal error code:

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

mbox The handle of the mailbox being defined.

pname A pointer to a null-terminated name string.

KS_DefMboxName

Example

In Example 5-2, the dynmbox variable contains the handle of a previously opened mailbox. Assign the name ^NewMbox to that mailbox so other users may reference it by name.

Example 5-2. Assign Mailbox Name

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

MBOX dynmbox;

if (KS_DefMboxName (dynmbox, "NewMbox") != RC_GOOD) {

... Naming operation failed. Deal with it here }

... naming operation was successful. Continue

See Also

KS_OpenMbox, page 188 KS_GetMboxName, page 178 KS_LookupMbox, page 186 KS_UseMbox, page 191

KS_DefMboxProp

KS_DefMboxProp

Define the properties of a mailbox.

Synopsis

void KS_DefMboxProp (MBOX mbox, const MBOXPROP *pmboxprop)

Inputs

Description

^The KS_DefMboxProp kernel service defines the properties of the mailbox specified in mbox using the values contained in the

MBOXPROP structure pointed to by pmboxprop.

Example 5-3 shows the organization of the ^MBOXPROP structure.

Example 5-3. Mailbox Properties Structure typedef struct

{

KATTR attributes; /* Waiting Order */

} MBOXPROP;

You may define the following mailbox attribute value:

The default value for the Waiting Order attribute can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER.

Output

This service does not return a value.

Error

This service may generate the following fatal error code:

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

mbox The handle of the mailbox being defined.

pmboxprop A pointer to a Mailbox properties structure.

Waiting Order Indicates the order in which tasks wait for access to a mailbox. The default order is by priority. Waiting Order can be changed to chronological ordering by ORing the ATTR_FIFO_ORDER constant into the attributes field.

KS_DefMboxProp

Example

In Example 5-4 on page 171, the Current Task defines the properties of the dynamic mailbox specified in dynmbox so that any tasks waiting to receive mail are ordered in descending order of task priority.

Example 5-4. Define Mailbox Properties

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

MBOX dynmbox;

MBOXPROP mprop;

KSRC ksrc;

KS_GetMboxProp (dynmbox, &mprop); /* Get properties */

/* use priority waiters */

mprop.attributes &= (~ATTR_FIFO_ORDER);

KS_DefMboxProp (dynmbox, &mprop); /* define properties */

... Continue

See Also

KS_GetMboxProp, page 180 INIT_MboxClassProp, page 184 KS_OpenMbox, page 188

KS_DefMboxSema

KS_DefMboxSema

Associate a semaphore with the Mailbox_Not_Empty event.

Synopsis

void KS_DefMboxSema (MBOX mbox, SEMA sema)

Inputs

Description

^The KS_DefMboxSema kernel service associates the semaphore specified in sema with the Mailbox_Not_Empty event of the mailbox specified in mbox. This action permits a task to synchronize with the occurrence of the mailbox event among a group of other events through the use of the KS_TestSemaM service or one of its variants.

Note: To use this service, you must enable the Semaphores attribute of the Mailbox class during system generation.

You do not need to use a semaphore to synchronize with the Mailbox_Not_Empty event unless you use it in conjunction with a multiple-event wait request. The RTXC Kernel provides that synchronization automatically and transparently.

Output

This service does not return a value.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

` FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.

mbox The handle of the mailbox being defined.

sema The handle of a semaphore to associate with the mailbox.

KS_DefMboxSema

Example

In Example 5-5 on page 174, the Current Task is servicing the HPMAIL and ^LPMAIL mailboxes. It needs to synchronize with the next message being sent to either mailbox, both of which are currently empty. The choice is not to poll the mailboxes but rather to define mailbox semaphores for the Mailbox_Not_Empty events for both mailboxes. Then the task uses the KS_TestSemaM service (or one of its variants) to wait for mail to be sent to either mailbox. When the task detects the presence of mail, it identifies the mailbox having the mail, receives it, and processes it. Upon completion of its processing, the task acknowledges the message to notify the sender that processing is finished.

KS_DefMboxSema

Example 5-5. Define Mailbox Semaphore

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

#include "kmbox.h" /* defines HPMAIL and LPMAIL */

#include "ksema.h" /* defines GOTHP and GOTLP */

char *msg;

MSGENV *penvelope;

SEMA sema;

const SEMA semalist[] = {

GOTHP, GOTLP,

(SEMA)0 /* list must be null terminated */

};

KS_DefMboxSema (HPMAIL, GOTHP); /* define semas for */

KS_DefMboxSema (LPMAIL, GOTLP); /* both mailboxes */

/* now test for a signal and wait if there is none */

sema = KS_TestSemaMW (semalist);

switch (sema) /* see which one was signaled */

{

case GOTHP:

/* receive message in HPMAIL from any task */

msg = KS_ReceiveMsg (HPMAIL, &penvelope);

... process received message break;

case GOTLP:

/* receive message in LPMAIL from any task */

msg = KS_ReceiveMsg (LPMAIL, &penvelope);

... process received message break;

}

/* acknowledge message receipt and processing */

KS_AckMsg (penvelope);

... continue

KS_DefMboxSema

See Also

KS_GetMboxSema, page 182 KS_ReceiveMsg, page 200 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMW, page 115 KS_TestSemaMT, page 112

KS_GetMboxClassProp

KS_GetMboxClassProp

Get the Mailbox object class properties.

Synopsis

const KCLASSPROP * KS_GetMboxClassProp (int *pint)

Input

pintA pointer to a variable in which to store the number of available dynamic mailboxes.

Description

^The KS_GetMboxClassProp kernel service obtains a pointer to the ^KCLASSPROP structure that was used during system initialization by the INIT_MboxClassProp service to initialize the Mailbox object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic mailboxes in the variable pointed to by pint.

Example 2-22 on page 62 shows the organization of the ^KCLASSPROP structure.

The attributes element of the Mailbox ^KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1.

Output

If successful, this service returns a pointer to a ^KCLASSPROP structure.

If the Mailbox class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).

If pint is not null, the service returns the number of available dynamic mailboxes in the variable pointed to by pint.

Table 5-1. Mailbox Class Attributes and Masks

Attribute Mask

Static Names ATTR_STATIC_NAMES

Dynamics ATTR_DYNAMICS

Semaphores ATTR_SEMAPHORES

KS_GetMboxClassProp

Example

In Example 5-6, the Current Task wants to gain access to the information contained in the ^KCLASSPROP structure for the Mailbox object class.

Example 5-6. Read Mailbox Object Class Properties

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

KCLASSPROP *pmboxclassprop;

int *free_dyn;

/* Get the mailbox kernel object class properties */

if ((pmboxclassprop = KS_GetMboxClassProp (&free_dyn)) == (KCLASSPROP *)0)

{

putline ("Mailbox Class not initialized");

} else {

... mailbox object class properties are available for use free_dyn contains the number of free dynamic mailboxes }

See Also

INIT_MboxClassProp, page 184

KS_GetMboxName

KS_GetMboxName

Get the name of a mailbox.

Synopsis

char * KS_GetMboxName (MBOX mbox)

Input

Description

^The KS_GetMboxName kernel service obtains a pointer to the null-terminated string containing the name of the mailbox specified in mbox. The mailbox may be static or dynamic.

Note: To use this service on static mailboxes, you must enable the Static Names attribute of the Mailbox class during system generation.

Output

If the mailbox has a name, this service returns a pointer to the null-terminated name string.

If the mailbox has no name, the service returns a null pointer (^{(char *)0}).

Error

This service may generate the following fatal error code:

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

Example

In Example 5-7 on page 179, the Current Task needs to report the name of the dynamic mailbox specified in dynmbox.

mbox The handle of the mailbox being queried.

KS_GetMboxName

Example 5-7. Read Mailbox Name

#include <stdio.h> /* standard i/o */

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

static char buf[128];

MBOX dynmbox;

char *pname;

if ((pname = KS_GetMboxName (dynmbox)) == (char *)0) sprintf (buf, "Mailbox %d has no name", dynmbox);

else

sprintf (buf, "Mailbox %d name is %s", dynmbox, pname);

putline (buf);

See Also

KS_DefMboxName, page 168 KS_OpenMbox, page 188

KS_GetMboxProp

KS_GetMboxProp

Get the properties of a mailbox.

Synopsis

void KS_GetMboxProp (MBOX mbox, MBOXPROP *pmboxprop)

Inputs

Description

^The KS_GetMboxProp kernel service obtains all of the property values of the mailbox specified in mbox in a single call. The service stores the property values in the ^MBOXPROP structure pointed to by pmboxprop.

Example 5-3 on page 170 shows the organization of the ^MBOXPROP structure.

The attributes property may have the following values:

Waiting Order indicates the ordering of tasks waiting for access to the mailbox.

If (attributes & ATTR_FIFO_ORDER) is not equal to 0, waiters have chronological ordering.

If (attributes & ATTR_FIFO_ORDER) equals 0, waiters are by priority.

Output

This service does not return a value.

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

` FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.

Example

In Example 5-8 on page 181, the Current Task needs to ensure that the properties of the dynamic mailbox specified in dynmbox are defined such that any tasks waiting to receive mail are ordered in descending order of task priority. The task first reads the existing

mbox The handle of the mailbox being queried.

pmboxprop A pointer to a Mailbox properties structure.

KS_GetMboxProp

properties of the specified mailbox and then forces priority order waiting.

Example 5-8. Read Mailbox Properties

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

MBOX dynmbox;

MBOXPROP mboxprop;

KS_GetMboxProp (dynmbox, &mboxprop); /* get properties */

/* force priority Waiting Order */

mboxprop.attributes &= (~ATTR_FIFO_ORDER);

/* define properties */

KS_DefMboxProp (dynmbox, &mboxprop);

... continue

See Also

KS_GetMboxProp, page 180

KS_GetMboxSema

KS_GetMboxSema

Get the semaphore handle associated with a Mailbox_Not_Empty event.

Synopsis

SEMA KS_GetMboxSema (MBOX mbox)

Input

Description

^The KS_GetMboxSema kernel service obtains the handle of the semaphore associated with the Mailbox_Not_Empty event for the static or dynamic mailbox specified in mbox.

You must have previously associated the semaphore with the mailbox event through a call to the KS_DefMboxSema service.

Note: To use this service, you must enable the Semaphores attribute of the Mailbox class during system generation.

Output

If the mailbox event and semaphore association exists, this service returns the handle of the semaphore as a ^SEMA type value.

If there is no such association for the mailbox event, the service returns a ^SEMA value of zero (0).

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

` FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.

Example

In Example 5-9 on page 183, the Current Task needs to know the handle of the Mailbox_Not_Empty semaphore associated with the MAINMBOX static mailbox. If it finds a semaphore already defined, it waits on that event or another associated with the ^MBXSEMA2

semaphore. If there is no semaphore defined, the Current Task mbox The handle of the mailbox being queried.

KS_GetMboxSema

defines the ^MBOX1SEMA semaphore, adds it to semalist, and waits on either that event or the one associated with ^MBXSEMA2.

Example 5-9. Read Mailbox Semaphore

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

#include "ksema.h" /* defines MBOX1SEMA, MBXSEMA2 */

#include "kmbox.h" /* defines MAINMBOX */

SEMA cause;

static SEMA semalist[] = {

0, /* to be filled in /*

MBXSEMA2,

(SEMA)0 /* end-of-list */

};

if ((semalist[0] = KS_GetMboxSema (MAINMBOX)) == (SEMA)0) {

/* no NE semaphore defined for mailbox MAINMBOX */

KS_DefMboxSema (MAINMBOX, MBOX1SEMA); /* define one */

semalist[0] = MBOX1SEMA;

}

/* there is now a NE semaphore defined for */

/* mailbox MAINMBOX */

/* wait for either event */

cause = KS_TestSemaMW (semalist);

if (cause == semalist[0]) {

... MAINMBOX received a message }

else (

... MBXSEMA2 was signaled )

See Also

KS_DefMboxSema, page 172

In document RTXC Kernel ServicesV2 Decrypted (Page 179-198)