![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 OverviewSyntax
generic type Message_Type is private; package V_MailboxesDescription
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.
Types
Table 6 lists the types in package V_Mailboxes.
Constants
Table 7 lists the constants in package V_Mailboxes.
Exceptions
Table 8 lists the exceptions in package V_Mailboxes.
.
This declaration creates a package that provides operations to pass characters via mailboxes:
with V_Mailboxes; package CHAR_BOX is new V_Mailboxes (Message_Type => CHARACTER);
The following declaration creates a package providing signal operations via mailboxes (i.e., messages of null length):
type signal_t is array(integer 1..0) of integer; package signal is new V_Mailboxes(Message_Type => signal_t);
Package Specification
with ADA_Krn_Defs; generic type Message_Type is private; package V_Mailboxes is pragma suppress(ALL_Checks); type mailbox_id is private; type mailbox_delete_option is (DELETE_OPTION_FORCE,DELETE_OPTION_WARNING); Wait_Forever : constant duration := -1.0; DO_NOT_Wait : constant duration := 0.0;
NO_Memory_FOR_Mailbox : exception; INVALID_Mailbox : exception; MAILBOX_TIMED_OUT : exception; MAILBOX_EMPTY : exception; MAILBOX_DELETED : exception; MAILBOX_FULL : exception; MAILBOX_NOT_EMPTY : exception; MAILBOX_IN_USE : exception; UNEXPECTED_V_Mailbox_ERROR : exception; BIND_Mailbox_NOT_SUPPORTED : exception; BIND_Mailbox_BAD_ARGUMENT : exception; NO_Memory_FOR_Mailbox_NAME : exception; MAILBOX_NAME_ALREADY_BOUND : exception; Resolve_Mailbox_NOT_SUPPORTED : exception; RESOLVE_NAILBOX_BAD_ARGUMENT : exception; Resolve_Mailbox_TIMED_OUT : exception; Resolve_Mailbox_FAILED : exception; NOT_A_Mailbox_NAME : exception;
type mailbox_result is (SENT,RECEIVED,TIMED_OUT,FULL,EMPTY,DELETED);
procedure Bind_Mailbox (name : in string; mailbox : in mailbox_id);
procedure Create_Mailbox (numberslots : in positive := 1; mailbox : out mailbox_id; attr : in ADA_Krn_Defs.a_Mailbox_attr_t := ADA_Krn_Defs.DEFAULT_Mailbox_ATTR);
function Create_Mailbox (numberslots : in positive := 1; attr : in ADA_Krn_Defs.a_Mailbox_attr_t := ADA_Krn_Defs.DEFAULT_Mailbox_ATTR); return mailbox_id;
function Current_Message_COUNT (mailbox : in mailbox_id) return natural; procedure Delete_Mailbox (mailbox : in mailbox_id; delete_option : in mailbox_delete_option);
procedure Read_Mailbox (mailbox : in mailbox_id; waittime : in duration; message : out Message_Type); procedure Read_Mailbox (mailbox : in mailbox_id; waittime : in duration; message : out Message_Type; result : out mailbox_result);
procedure Resolve_Mailbox (name : in string; mailbox : out mailbox_id; wait_time : in duration := Wait_Forever); function Resolve_Mailbox (name :in string; wait_time : in duration := Wait_Forever) return mailbox_id;
procedure Write_Mailbox (mailbox : in mailbox_id; message : in Message_Type; lifo_order : in boolean := false);
procedure Write_Mailbox (mailbox : in mailbox_id; message : in Message_Type; result : out mailbox_result; lifo_order : in boolean := false);
private type mailbox_rec; type mailbox_id is access mailbox_rec; end V_Mailboxes;
Procedures and Funtions in Package V_Mailboxesprocedure Bind_Mailbox
Syntax
procedure BIND_Mailbox (name: in string;
mailbox : in mailbox_id);
Arguments
- name
Mailbox's name. The name can be any sequence of characters. An exact match is done for all name searches. (My_Mailbox differs from my_Mailbox).
- mailbox
Description
Bind_Mailbox binds a name to a previously created mailbox.
Exceptions
- No_Memory_For_Mailbox_Name
Name could not be bound because of insufficient memory.
- Bind_Mailbox_Not_Supported
Name services are not supported by the underlying RTS.
- Bind_Mailbox_Bad_Argument
- Mailbox_Name_Already_Bound
Name was already bound to another object or procedure.
Warning: For native, names are only known within a single program. Name binding and resolution services are more applicable to the cross-target environment.
function/procedure Create_Mailbox
Syntax
function Create_Mailbox (numberslots: in positive := 1;
attr
: in ADA_Krn_Defs.a_Mailbox_attr_t := ADA_Krn_Defs.DEFAULT_Mailbox_ATTR) return mailbox_id;
procedure Create_Mailbox (numberslots : in positive := 1; mailbox: out mailbox_id;
attr
: in ADA_Krn_Defs.a_Mailbox_attr_t := ADA_Krn_Defs.DEFAULT_Mailbox_ATTR);
Arguments
- attr
Points to an Ada_Krn_Defs.Mailbox_Attr_T record. This record contains the mailbox attributes, which depend on the underlying threaded runtime.
The attr parameter has been defaulted to Default_Mailbox_Attr. Unless you want to do something special, the default will suffice. The Rational Exec Microkernel defaults to FIFO queuing when a task blocks waiting to read a message.
For the Rational Exec Microkernel, use: Ada_Krn_Defs.Default_Mailbox_Intr_Attr to protect the mailbox critical region by disabling all interrupts. Use the subprogram Ada_Krn_Defs.Mailbox_Intr_Attr_Init to initialize the attributes so that a subset of the interrupts are disabled.
If the mailbox is accessed from an Isr, it must be protected by disabling interrupts.
- mailbox
- numberslots
The number of message slots to have in the mailbox (maximum number of messages the mailbox can hold).
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
function Current_Message_COUNT (mailbox: in mailbox_id) return natural;
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
procedure DELETE_Mailbox (mailbox : in mailbox_id; delete_option : in mailbox_delete_option);Arguments
- delete_option
The action to be taken if the mailbox is in use or not empty.
- Delete_Option_Force
Ready all waiting tasks. These task calls to Read_Mailbox raise the exception Mailbox_Deleted or return the value Deleted.
- Delete_Option_Warning
If there are messages in the mailbox, raise the exception Mailbox_Not_Empty in the calling task.
If tasks are waiting at the mailbox, raise the exception Mailbox_In_Use in the calling task.
- mailbox
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
- Invalid_Mailbox
Mailbox_ID does not identify an existing mailbox.
- Mailbox_In_Use
mailbox is not empty and delete_option is Delete_Option_Warning.
- Mailbox_Not_Empty
Tasks waiting at mailbox and delete_option is Delete_Option_Warning.
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
procedure Read_Mailbox (mailbox : in mailbox_id; waittime : in duration; message : out Message_Type); procedure Read_Mailbox (mailbox : in mailbox_id; waittime : in duration; message : out Message_Type; result : out mailbox_result);Arguments
- mailbox
- message
Message read from the mailbox.
- waittime
Time (in duration seconds) to wait for a message.
- result
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
- Invalid_Mailbox
Mailbox_ID specifies a nonexistent mailbox.
- Mailbox_Deleted/Deleted
mailbox is deleted during the read operation.
- Mailbox_Empty/Empty
An unwaited read is performed and there is no a message in the mailbox.
- Mailbox_Timed_Out/Timed_Out
Timed read is performed and no message is received in the specified time interval.
- /Received
Threaded Runtime
Read_Mailbox is layered on Ada_Krn_I.Mailbox_Read.
procedure/function Resolve_Mailbox
Syntax
procedure Resolve_Mailbox (name : in string; mailbox : out mailbox_id; wait_time : in duration := Wait_Forever); function Resolve_Mailbox (name : in string; wait_time : in duration := Wait_Forever) return mailbox_id;Arguments
- name
- mailbox
- wait_time
Amount of time the user is willing to wait for the name to be bound. Two predefined values that are allowable are:
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
- Not_A_Mailbox_Name
Raised by Resolve_Mailbox 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 by Resolve_Mailbox if a nonwaited 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 underlying RTS.
- Resolve_Mailbox_Timed_Out
Raised by Resolve_Mailbox if a timed wait was attempted and the name wasn't bound to a mailbox in the given time interval.
Warning: For native, names are only known within a single program. Name binding and resolution services are more applicable to the cross-target environment.
procedure Write_Mailbox
Syntax
procedure Write_Mailbox (mailbox : in mailbox_id; message : in Message_Type; lifo_order : in boolean := false); procedure Write_Mailbox (mailbox : in mailbox_id; message : in Message_Type; result : out mailbox_result; lifo_order : in boolean := false);Arguments
- lifo_order
Determines where the message is added to the queue. If it is set to False, the message is placed in the queue in FIFO order. If it is set to True, the message is placed on the queue in LIFO order. This feature aids in porting PSOS applications which make use of the "jam" feature in the mailbox services.
- mailbox
- message
Message to be written to the mailbox.
- result
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
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2003, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |