TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Mailboxes (Package V_Mailboxes)

This section contains an overview describing this package. This overview section is followed by a detailed description of each subprogram in this package.

The following topics are covered in this section:


Package Overview

Syntax

Description

Package V_Mailboxes is a generic package that provides mailbox operations. Use mailboxes for the unsynchronized passing of data between tasks or between an interrupt handler and a task. V_Mailboxes has been layered upon the Ada Kernel mailbox objects.

The procedure Create_Mailbox creates a mailbox for passing objects of the type used to instantiate the generic package.

Read_Mailbox reads messages from a mailbox on a first-in/first-out (FIFO) basis. A parameter can be used to specify how long the task is willing to wait for a message if one is not immediately available. The queuing order for tasks waiting to read a message depends on the attributes passed to Create_Mailbox. The default is FIFO.

Write_Mailbox writes a message to the mailbox, awakening a task waiting on the mailbox if any are waiting. If the awoken task is of sufficient priority, it preempts the current running task.

Delete_Mailbox deletes a mailbox. The user must specify the action to be taken if there are currently tasks waiting on the mailbox.

Read_Mailbox and Write_Mailbox are declared as overloaded procedures to allow the user to select the method of error notification. If a result parameter is provided in the call, a result status is returned in the parameter; otherwise an exception is raised if an error occurs.

Bind_Mailbox and Resolve_Mailbox allow a mailbox to be shared between programs. Bind_Mailbox binds a name to a mailbox previously created in the current program. Resolve_Mailbox resolves a name into a mailbox that was created and bound in another program.

Message_Type is the type of object that can be passed using the operations provided by an instantiation.

Note: The Message_Type, with which V_Mailboxes is instantiated, must have a size known by the compiler at compile time. For example, it should not be an unconstrained array type. This is because the memory for the mailbox queue is pre-allocated by the runtime at the time of the instantiation, and a simple mechanism of incrementing a pointer by the size of the object is used to allocate individual mailbox objects from this pre-allocated memory.

If a task is aborted while accessing a mailbox, the resource is permanently locked.

Package Procedures and Functions

Table 5 lists the procedures and functions in package V_Mailboxes with a brief description of each subprogram.

Table 5 Procedures and Functions
Name
Description
procedure Bind_Mailbox
Bind a name to a mailbox.
function/procedure Create_Mailbox
Create and initialize a mailbox.
procedure Delete_Mailbox
Delete a mailbox.
procedure Read_Mailbox
Retrieve a message from a mailbox.
procedure/function Resolve_Mailbox
Resolve a name into a mailbox.
procedure Write_Mailbox
Write a message into a mailbox.
function Current_Message_Count
Return the number of unread messages.

Types

Table 6 lists the types in package V_Mailboxes.

Table 6 Types
Name
Description
Mailbox_Delete_Option
Specifies the action to take during a call to Delete_Mailbox if tasks are waiting on the mailbox that is to be deleted or if the mailbox contains messages. Possible values are:

Delete_Option_Force
Delete_Option_Warning

Mailbox_ID
A private type used to identify mailboxes. The compiler type checks mailbox parameters to ensure that the buffer type can be passed using the operations provided by an instantiation.
Mailbox_Result
Returns the completion status of the versions of Read_Mailbox and Write_Mailbox that return a status. Possible values are:

Deleted
Empty
Full
Received
Sent
Timed_Out

Constants

Table 7 lists the constants in package V_Mailboxes.

Table 7 Constants
Name
Description
Wait_Forever
Passed to the Waittime parameter of Read_Mailbox to specify that the mailbox should be waited on until a message is received. Additionally, this constant may be used with Resolve_Mailbox to specify waiting indefinitely or not at all for the name to be bound.
Do_Not_Wait
Passed to the Waittime parameter of Read_Mailbox to specify that a non-waited read of the mailbox should be performed Additionally, this constant may be used with Resolve_Mailbox to specify waiting indefinitely or not at all for the name to be bound.

Exceptions

Table 8 lists the exceptions in package V_Mailboxes.

Table 8 Exceptions
Name
Description
Bind_Mailbox_Bad_Argument
Raised if Bind_Mailbox is called with a null name.
Bind_Mailbox_Not_Supported
Raised if name services are not supported by the RTS.
Invalid_Mailbox
Raised if the mailbox ID passed to a mailbox operation does not identify an existing mailbox.
Mailbox_Deleted
Raised if the mailbox is deleted during the read operation.
Mailbox_Empty
Raised if an unwaited read is performed and there is no message in the mailbox.
Mailbox_Full
Raised if an attempt is made to write to a full mailbox.
Mailbox_In_Use
Raised if you attempt to delete a mailbox that a task is waiting for and the delete option is Delete_Option_Warning.
Mailbox_Name_Already_Bound
Raised if an attempt is made to bind a name to a mailbox and the name has already been bound to another object.
Mailbox_Not_Empty
Raised when you attempt to delete a mailbox that is not empty and the delete option is Delete_Option_Warning.
Mailbox_Timed_Out
Raised if a timed wait is performed and a message does not arrive in the specified time interval.
No_Memory_For_Mailbox
Raised if insufficient memory is available to create the mailbox.
No_Memory_For_Mailbox_Name
Raised if an attempt is made to bind a name to a mailbox and there is insufficient memory.
Not_A_Mailbox_Name
Raised if the name is bound, but not to a mailbox object.
Resolve_Mailbox_Bad_Argument
Raised if Resolve_Mailbox is called with a null name.
Resolve_Mailbox_Failed
Raised if a non-waited attempt was made to resolve a name to a mailbox and the name wasn't already bound.
Resolve_Mailbox_Not_Supported
Raised if name services are not supported by the RTS.
Resolve_Mailbox_Timed_Out
Raised if a timed wait was attempted and the name wasn't bound to a mailbox in the given time interval.
Unexpected_V_Mailbox_Error
Raised if an unexpected error occurs during a V_Mailbox operation.
.

Example

This declaration creates a package that provides operations to pass characters via mailboxes:

The following declaration creates a package providing signal operations via mailboxes (i.e., messages of null length):

Package Specification


Procedures and Funtions in Package V_Mailboxes

procedure Bind_Mailbox

Syntax

Arguments

Description

Bind_Mailbox binds a name to a previously created mailbox.

Exceptions

function/procedure Create_Mailbox

Syntax

Arguments

Description

Create_Mailbox creates and initializes a mailbox. Two versions of the call are supplied: a procedure that returns the mailbox ID as an out parameter and a function returning the mailbox ID. To notify other tasks of the mailbox ID, place the Mailbox_ID variable at a package level.

The created mailbox can be shared with other programs by using the Bind_Mailbox/Resolve_Mailbox services.

Exceptions

Threaded Runtime

Create_Mailbox is layered on Ada_Krn_I.Mailbox_Init. See the source code for Ada_Krn_I.Mailbox_Init for more details about mailbox attributes.

function Current_Message_Count

Syntax

Arguments

Description

The function Current_Message_Count takes one parameter, the mailbox ID, and returns the number of unread messages currently in the specified mailbox.

Threaded Runtime

Current_Message_Count is layered upon Ada_Krn_I.Mailbox_Get_Count.

procedure Delete_Mailbox

Syntax

Arguments

Description

The procedure Delete_Mailbox removes a mailbox from the system. Deleting a mailbox releases all of the buffer space used for the mailbox.

If a mailbox is shared between programs by using the Bind_Mailbox/Resolve_Mailbox services, it must be deleted only in the program where it was created.

Exceptions

Threaded Runtime

Delete_Mailbox is layered upon Ada_Krn_I.Mailbox_Destroy.

Note: For LynxOS, there is no way to detect whether a task is waiting to read a mailbox, therefore Mailbox_In_Use will never be raised. Care must be taken to ensure that no task is attempting to read the mailbox.

procedure Read_Mailbox

Syntax

Arguments

Description

Procedure Read_Mailbox retrieves messages from a specified mailbox. To indicate whether the task waits forever or not at all for a message, specify the constants Wait_Forever and Do_Not_Wait, respectively.

Do not call Read_Mailbox from an interrupt service routine unless Waittime is specified as Do_Not_Wait.

Exceptions/Results

Threaded Runtime

Read_Mailbox is layered on Ada_Krn_I.Mailbox_Read.

procedure/function Resolve_Mailbox

Syntax

Arguments

Description

Resolve_Mailbox resolves a name into a mailbox that was created and bound in another program. Two versions are supplied, a procedure that returns mailbox id as an out parameter or a function returning the mailbox id. Resolve_Mailbox first attempts to find an already bound name that exactly matches the name parameter. For a match, it returns immediately. Otherwise, it returns according to the wait_time parameter.

Exceptions

procedure Write_Mailbox

Syntax

Arguments

Description

If any tasks are waiting at the mailbox, the first-queued waiting task receives the message and becomes ready-to-run. If that task is of higher priority than the current task, it preempts the current task.

Write_Mailbox can be called from an interrupt service routine. If the write operation awakens a task with a higher priority than the interrupted task, the interrupted task is preempted upon completion of interrupt processing.

The interrupt protected form of mailbox must be used when the mailbox is written from an Isr.

Exceptions/Results

Threaded Runtime

Write_Mailbox is layered upon Ada_Krn_I.Mailbox_Write.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2003, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS