TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Tasking Extensions (Package V_Xtasking)

This chapter 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

Description

Package V_Xtasking (extended tasking) provides operations that are performed on Ada tasks. Xtasking services augment the services defined by the language.

Begin Tornado Only

The first free spare field in the Tornado task control block is used for the user field accessed by the Set_User_Field and Current_User_Field services.

The time-slicing parameters affect the entire Tornado system.

The Start_Program service starts a new program via the Tornado taskSpawn() service. Task and program callouts are supported by installing a Tornado hook which executes any installed VADSexec callouts. The hook is not added until a callout is created, and is removed when the last callout is deleted.

End Tornado Only

Suspend_Task immediately inhibits the task from running regardless of its current state. Resume_Task allows a suspended task to run when it is in a ready-to-run state. Neither Suspend_Task or Resume_Task affects the task state.

In addition to Suspend_Task and Resume_Task, V_XTasking provides operations to determine the current task and get and set these task parameters: priority, time slice interval, user field, fast rendezvous enabled, callable attribute, and terminated attribute. (The attribute parameters cannot be set.) Additionally, V_Xtasking provides operations to get and set the global time slicing enabled configuration parameter.

Services to disable and enable task preemption are provided. In addition, services to disable and enable the current task from being completed/terminated by an Ada abort are available.

Ada tasks and programs are layered on the underlying OS tasks and programs. Services are provided for mapping an Ada task ID to an OS task ID and vice-versa. Services are also provided for mapping program IDs.

A service is provided to call a procedure in another program. This service is normally used in conjunction with the V_Names bind/resolve procedure services.

Services are also provided to install subprogram callouts resident in the user program for program, task, and idle events. A callout can be installed for the following program events: exit, unexpected exit (main program abandoned because of an unhandled exception), or switch. A callout can be installed for the following task events: creation, switch and completion. A callout can be called whenever the kernel is in its idle state. Additionally, user-defined storage can be allocated in the control block for a task.

Ada Tasking has the global flag Exit_Disabled_Flag which can be set to True to inhibit the program from exiting. Services are provided to get and set this flag.

Package Procedures And Functions

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

Table 25 Procedures and Functions
Name
Description
function Allocate_Task_Storage
Allocate storage in the task control block. The function returns the storage ID to be used in subsequent Get_Task_Storage or Get_Task_Storage2 service calls.
function Callable
Return the P'Callable attribute for the specified task.
function Current_Exit_Disabled
Return current value.
function Current_Fast_Rendezvous_Enabled
Return the value of the Fast_Rendezvous_Enabled flag of the current task.
function Current_Priority
Return the priority of the specified task.
function Current_Program
Return the program ID of the current task.
function Current_Task
Return the task ID of the current task.
function Current_Time_Slice
Return the current time slice interval of the specified task.
function Current_Time_Slicing_Enabled
Return the current value of the kernel Time_Slicing_Enabled configuration parameter.
function Current_User_Field
Return the current value of the specified task user-modifiable field.
procedure Disable_Preemption
Inhibit the current task from being preempted. The procedure does not disable interrupts. (Should always be paired with Enable_Preemption)
procedure Disable_Task_Complete
Disable the current task from being completed and terminated when aborted. Must be paired with Enable_Task_Complete.
procedure Enable_Preemption
Allow the current task to be preempted. (Should always be paired with Disable_Preemption)
procedure Enable_Task_Complete
Enable the current task to be completed and terminated when aborted. Must be paired with Disable_Task_Complete
function Get_Program
Return the program_id of the specified task.
function Get_Program_Key
Return the user defined key for the specified program.
function Get_Task_Storage
Return the starting address of the task storage area of the specified task and storage ID.
function Get_Task_Storage2
Return the starting address of the task storage area using the OS ID of the task.
function ID
Return an identifier for an Ada program or task given the underlying OS program or task ID.
procedure Install_Callout
Install a procedure to be called at a program exit, program switch, task create, task switch, task complete, or idle event.
procedure Inter_Program_Call
Call a procedure in another program.
function Os_Id
Return the underlying OS program or task ID given the Ada program or task ID.
procedure Resume_Task
Ready the named task for execution.
procedure Set_Exit_Disabled
Change the kernel Exit_Disable_Flag to inhibit or allow the program to exit.
procedure Set_Fast_Rendezvous_Enabled
Change the Fast_Rendezvous_Enabled flag for the current task to a new value.
procedure Set_Is_Server_Program
Mark the current program as a server program.
procedure Set_Priority
Change the priority of the specified task.
procedure Set_Time_Slice
Change time slice interval of specified task.
procedure Set_Time_Slicing_Enabled
Set kernel configuration parameter Time_Slicing_Enabled.
procedure Set_User_Field
Change the value of the specified task user-modifiable field.
function Start_Program
Start another, separately linked program identified by its link block, and return the Program_ID of the just started program.
procedure Suspend_Task
Cause a running task to become suspended.
function Terminated
Return the P'Terminated attribute for the specified task.
generic function V_ID
Return an identifier for a task, given a task object of the task type used to instantiate the generic.

Types

Table 26 lists the types in package V_Xtasking.

Table 26 Types
Name
Description
Callout_Event_T
Type of program, tasking, or idle event that can have a callout procedure installed with the Install_Callout service. Possible values are:

Exit_Event
Idle_Event
Program_Switche_Event
Task_Complete_Event
Task_Create_Event
Task_Switch_Evernt
Unexpected_Exit_Event

Os_Program_ID
Type of the underlying OS program control block.
Os_Task_ID
Type of the underlying OS task control block.
Program_ID
Type of the Ada program control block. This type is defined in package System.
Task_ID
Type of the Ada task control block. This type is defined in package System.
Task_Storage_ID
Provides an identifier for user-defined storage in a task control block created and returned by the Allocate_Task_Storage service and passed to the Get_Task_Storage or Get_Task_Storage2 extended tasking services.
Xtasking_Result
Type of the result codes returned by the non-exception-raising versions of the Suspend_Task and Resume_Task routines. Possible values are:

Not_Resumed
Not_Suspended
Resumed
Suspended

Subtypes

Table 27 lists the subtypes in package V_Xtasking.

Table 27 Subtypes
Name
Description
User_Field_T
Type of user-modifiable field stored in task control block where User_Field_T'Size = Integer'Size.
User_Field2_T
Type of user-modifiable field stored in the task control block where User_Field2_T'Size = Address'Size.

Constants

Table 28 lists the constants in package V_Xtasking.

Table 28 Constants
Name
Description
Null_Task_Name
null task constant.
No_Task_Storage_ID
Returned by Allocate_Task_Storage when no more space is available in the task control block.
Null_Os_Task_Name
null OS task constant.
Null_Os_Program_Name
null OS program constant.

Exceptions

Table 29 lists the exceptions in package V_Xtasking.

Table 29 Exceptions
Name
Description
Invalid_Resume
Raised by resume task if the task cannot be resumed. This occurs if the task is not currently suspended. Not used with the Rational Exec Microkernel.
Invalid_Suspend
Raised by suspend task if the task cannot be suspended. This occurs if the task is not currently runnable. Not used with the Rational Exec Microkernel.
Unexpected_V_Xtasking_Error
Raised if an unexpected error occurs in an V_Xtasking routine.

Package Specification


Procedures and Functions in Package V_Xtasking

function Allocate_Task_Storage

Syntax

Arguments

Description

.This service allocates storage in the task control block. It returns the ID to be used in subsequent Get_Task_Storage or Get_Task_Storage2 service calls.

The task storage allocation is applicable only to tasks in the current program.

Exceptions

Threaded Runtime

Allocate_Task_Storage is provided for Rational Exec Microkernel. However, this service may not be supported by other underlying threaded runtimes. It is not supported for LynxOS.

function Callable

Syntax

Arguments

Description

The function Callable returns the value of the specified task's P'Callable attribute. When the specified task is completed, terminated, or executes abnormally, Callable returns the Boolean value False. Under all other conditions, Callable returns the Boolean value True. Referencing a nonexistent task or a task that has not yet been created yields indeterminate values.

function Current_Exit_Disabled

Syntax

Description

.This function returns the current value for the Ada tasking global variable Exit_Disabled_Flag. When True, the Ada application program is inhibited from exiting.

function Current_Fast_Rendezvous_Enabled

Syntax

Description

This function returns the value for the current Ada task Fast_Rendezvous_Enabled flag.

Note: For LynxOS, calls to this routine are silently ignored.

function Current_Priority

Syntax

Arguments

Description

Current_Priority returns the current priority of the specified task. This may be the task priority as specified by a pragma Priority, the default task priority, the priority of a task it is in rendezvous with (if the task is in rendezvous with a higher priority task), or the task priority changed via Set_Priority.

function Current_Program

Syntax

Description

.This function returns the program ID of the current program.

Threaded Runtime

Current_Program is provided for Rational Exec Microkernel. However, this service may not be supported by other underlying threaded runtimes. Not supported by LynxOS.

function Current_Task

Syntax

Description

This function returns the task ID of the current task.

Example

The following call suspends the currently running task:

function Current_Time_Slice

Syntax

Arguments

Description

The function Current_Time_Slice returns the value of the specified task's current time slice interval. Current_Time_Slice requires a task ID for a parameter. If you do not supply a task ID, the routine defaults to the current task.

Threaded Runtime

This service is provided for Rational Exec Microkernel. However, this service may not be supported by other underlying threaded runtimes. Not supported by LynxOS.

function Current_Time_Slicing_Enabled

Syntax

Description

The function Current_Time_Slicing_Enabled returns a boolean value indicating the current value of the kernel Time_Slicing_Enabled configuration parameter.

Threaded Runtime

This service is provided for Rational Exec Microkernel and LynxOS. However, this service may not be supported by other underlying threaded runtimes.

function Current_User_Field

Syntax

Arguments

Description

The function Current_User_Field returns the value of the user-modifiable field of a specified task. If no task ID is specified for the parameter task_name, the routine defaults to the current task. Either an Integer'Size value (via User_Field_T) or an Address'Size value (via User_Field2_T) can be retrieved from the task's User_Field. The Apex runtime system does not use the User_Field.

procedure Disable_Preemption

Syntax

Description

The procedure Disable_Preemption inhibits the current task from being preempted. This service does not disable signals. Task switching may still occur through the direct action of the currently running task making another higher priority task available to run. Signals still occur and Isr code is executed, but no other tasks run as a result of a signal.


Warning: This procedure must be paired with procedure Enable_Preemption.

Threaded Runtime

Rational Exec Microkernel maintains a preemption depth count for each task. This preemption depth is saved/restored at a task switch. Each call to Disable_Preemption increments the depth. A nonzero depth count inhibits preemption. However, another task may run if the task calls a kernel service that causes it to block. Each call to Enable_Preemption decrements the depth. When the depth is zero, the task can be preempted.

The preemption depth count allows these procedures to be nested. Ultimately, however, they must be paired.

Other threaded runtimes may not support the disabling of preemption.

procedure Disable_Task_Complete

Syntax

Description

Disable_Task_Complete disables the current task from being completed and terminated when aborted. If the task is aborted after Disable_Task_Complete is called, its completion is deferred until its mate, Enable_Task_Complete, is called. Calls to Disable_Task_Complete and Enable_Task_Complete can be nested.

These services can be used as follows to inhibit a task from being completed after it has acquired a sharable resource such as a semaphore:

procedure Enable_Preemption

Syntax

Description

The procedure Enable_Preemption allows the current task to be preempted. Note that preemption is enabled by default when a task is created.


Warning: This procedure must be paired with procedure Disable_Preemption. Do not call Enable_Preemption before calling Disable_Preemption.

Threaded Runtime

Rational Exec Microkernel maintains a preemption depth count for each task. This preemption depth is saved/restored at a task switch. Each call to Disable_Preemption increments the depth. A nonzero depth count inhibits preemption. However, another task may run if the task calls a kernel service that causes it to block. Each call to Enable_Preemption decrements the depth. When the depth is zero, the task can be preempted.

Other threaded runtimes may not support the disabling of preemption.

procedure Enable_Task_Complete

Syntax

Description

Enable_Task_Complete enables the current task to be completed and terminated when aborted. This procedure must be paired with Disable_Task_Complete. They can be nested. There is no return if they are not nested and the current task has been marked abnormal by a previous abort.

These services can be used as follows to inhibit a task from being completed after it has acquired a sharable resource such as a semaphore:

function Get_Program

Syntax

Arguments

Description

This function returns the program ID for the specified task.

Threaded Runtime

This service is provided for Rational Exec Microkernel. However, this service may not be supported by other underlying threaded runtimes Not supported by LynxOS.

function Get_Program_Key

Syntax

Arguments

Description

.This function returns the user-defined key for the specified program. The key is stored when the program is started via the Start_Program service. The main program has a predefined key of System.Address'Ref(0).

Threaded Runtime

This service is provided for Rational Exec Microkernel. However, this service may not be supported by other underlying threaded runtimes. Not supported by LynxOS, as such it always returns system NO_ADDR.

function Get_Task_Storage

Syntax

Arguments

Description

The service returns the starting address of the task storage area associated with the storage_id using the Ada task identifier (instead of the OS task identifier).

Threaded Runtime

This service is provided for Rational Exec Microkernel. However, this service may have different semantics or may not be supported by other underlying threaded runtimes. Not supported by LynxOS, as such it always returns system NO_ADDR.

function Get_Task_Storage2

Syntax

Arguments

Description

The service returns the starting address of the task storage area associated with the storage_id using the OS ID of the task (instead of the Ada task identifier).

Threaded Runtime

This service is provided for Rational Exec Microkernel. However, this service may not be supported by other underlying threaded runtimes. Not supported by LynxOS, as such it always returns system NO_ADDR.

function ID

Syntax

Arguments

Description

If a task address is given, ID returns a task identifier for any task. The ID of a task object of a task type may be determined using either this function or a function created by an instantiation of the generic function V_ID. However, the ID of a task that is not a task object of a task type may only be determined by the ID function. This function can be used for all tasks.

ID also converts from an underlying thread or operating system identifier to an Ada task ID or Ada program ID.

Note: The ID function for converting a Task_Address no longer needs to be called. The T'Task_ID attribute returns the ID for a task which may be used by the V_Xtasking services.

Example

The following code fragment uses the ID function with the Resume_Task operation to resume the task Other_Task:

Error Results

procedure Install_Callout

Syntax

Arguments

Description

This service installs a procedure to be called at a program, task, or idle event. Callouts can be installed for Exit_Event, Unexpected_Exit_Event, Program_Switch_Event, Task_Create_Event, Task_Switch_Event, Task_Complete_Event, or Idle_Event.

The Exit_Event, Unexpected_Exit_Event, and Idle_Event callout procedures are called in LIFO (last-in/first-out) order. The remaining callout procedures are called in the order in which they were installed.

The callouts reside in the user program space. The Exit_Event and Unexpected_Exit_Event callouts are called in the context of the program's main task. The remaining callouts are called directly from kernel logic and can only call kernel services that are reentrant, the same services Callable from Isrs. The service of most interest is Calendar.Clock which is called for time stamping.

Before any non-Program_Switch_Event callout procedure is invoked, the Stack_Limit in the user program is set to 0 to negate any stack limit checking. Therefore, the callout procedures do not need to be compiled with stack limit checking suppressed. However, the Stack_Limit is not zeroed before calling the Program_Switch_Event callout. It needs to be compiled with stack limit checking suppressed.

Except for Program_Switch_Event or Idle_Event, the callouts are installed and called only for the program in which they reside.

An overview of the different callout events is as follows:

Exceptions

Threaded Runtime

This service is provided as described for Rational Exec Microkernel. Other underlying threaded runtimes may support different callout events. However, all implementations are expected to support Exit_Event and Unexpected_Exit_Event.

procedure Inter_Program_Call

Syntax

Arguments

Description

Procedure Inter_Program_Call does an indirect call to a procedure in another program.

procedure_program can be set to three different values: Program_Self(), No_Program_ID, or the program ID of the program containing the called procedure.

If procedure_program is set to Program_Self() or No_Program_ID, the procedure is called directly without switching the current program or stack limit.

If procedure_program is set to No_Program_ID and the called procedure is in another program, the called procedure must use pragma Suppress(all_checks) and it cannot raise any Ada exceptions. In addition, if it calls any kernel services, the calling program is still the parent and owner of any created tasks or memory allocated from the kernel. Any Ada new memory allocations will cause heap corruption if more memory is needed from the kernel and the calling program terminates before the called program does. Therefore, Ada new memory allocation is strongly discouraged for this case.

If procedure_program is set to the program ID of the program containing the called procedure, and if the called procedure does any task creation or kernel memory allocations, the program containing the called procedure is the parent and owner.

Normally, Inter_Program_Call is used in conjunction with the V_Names.Bind_Procedure and V_Names.Resolve_Procedure services where a name has been bound to the procedure to be called.

If the program containing the called procedure doesn't have any active tasks, the V_Xtasking.Set_Is_Server_Program service should be called there during elaboration to mark it as a server.

The argument parameter is passed as the only argument to the called procedure. The called procedure has the following profile:

During the call, the current task is disabled from being completed and terminated by an Ada abort.

Before doing the call, the current program is switched. Also, the stack_limit in the program containing the called procedure is switched. Before returning, everything is restored.

Note that the Program_Switch_Event callouts are not called. The task's parent program is not switched. The Program_Switch_Event callouts are only called when the parent program switches (that is, when you switch to another task that is in another parent program).

Ada exceptions can be raised and handled in the called procedure. However, Inter_Program_Call does not handle the propagation of Ada exceptions across interprogram calls. Therefore, the called procedure must have a handler for all possible Ada exceptions. An Ada exception raised in the called procedure can have an outer handler that maps the exception to error status returned to the calling program. The calling program can then decode the error status and reraise the Ada exception.

Threaded Runtime

This service is provided as described for the Rational Exec Microkernel. However, this service may not be supported by other underlying OS threads.


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 Os_Id

Syntax

Arguments

Description

Os_ID returns the underlying OS task or program identifier given either the Ada task ID or the Ada program ID.

procedure Resume_Task

Syntax

Arguments

Description

Resume_Task only readies a task suspended by Suspend_Task. The task does not execute unless it is the highest priority ready task.

This service can only be used to activate a task suspended by a call to Suspend_Task.

Exceptions/Results

Threaded Runtime

Note that exceptions and results are OS dependent. For the Rational Exec Microkernel, Resume_Task always returns Resumed (or no exception is raised). Each task has a suspend flag. Resume_Task sets the task suspend flag to False. If the task is ready to run, it is put on the run queue.

The semantics of the Resume_Task service are dependent on the underlying operating system. Resume_Task is layered on Ada_Krn_I.Task_Resume.

procedure Set_Exit_Disabled

Syntax

Arguments

Description

Set_Exit_Disabled sets the Ada tasking global variable, Exit_Disabled_Flag. This flag is initialized to False, allowing the application program to exit when no tasks are on either the run or delay queue. This service is called, with new_value := True, to inhibit the program from exiting. It is normally called after the application program attaches an Isr. The program is allowed to exit with a subsequent call, where new_value := False.

procedure Set_Fast_Rendezvous_Enabled

Syntax

Arguments

Description

Set_Fast_Rendezvous_Enabled sets the Fast_Rendezvous_Enabled flag for the current Ada task.

If Fast_Rendezvous_Enabled is disabled in the configuration table, it can never be enabled.

Normally, fast rendezvous would need only to be disabled for multiprocessor Ada where the accept body must execute in the acceptor task bound to a processor.

Note: For LynxOS, calls to this routine are silently ignored.

procedure Set_Is_Server_Program

Syntax

Description

Procedure Set_Is_Server_Program marks the current program as a server program. If the current program won't have any active tasks and it contains procedures called via V_Xtasking.Inter_Program_Call, this procedure should be called.

A server program has the following attributes. It is automatically terminated when no nonserver program is active. It is inhibited from exiting prematurely or being terminated. Also, when its main procedure returns (at end of server's elaboration), the main task's stack is freed and its microkernel thread is stopped/freed.

Threaded Runtime

Set_Is_Server_Program is provided as described for the Rational Exec Microkernel. However, this service may not be supported by other underlying OS threads. Not supported by LynxOS.

procedure Set_Priority

Syntax

Arguments

Description

Set_Priority enables you to change the priority of a specified task. Task scheduling is then re-evaluated.


Warning: Use this service with extreme caution because it may interfere with the kernel scheduling.

procedure Set_Time_Slice

Syntax

Arguments

Description

Set_Time_Slice enables you to change the time slice interval of a specified task. Set_Time_Slice requires two parameters: the duration of the new time slice interval (new_interval) and the ID of the task that is to have the time slice interval changed (task_name).

Threaded Runtime

This service is provided for Rational Exec Microkernel. However, this service may have different semantics or may not be supported by other underlying threaded runtimes.

procedure Set_Time_Slicing_Enabled

Syntax

Arguments

Description

The procedure Set_Time_Slicing_Enabled enables you to change the value of the kernel Time_Slicing_Enabled configuration parameter. If no new value is specified for this function, the function defaults to a Boolean value of True.

Threaded Runtime

This service may not be supported by other underlying threaded runtimes. Not supported on LynxOS.

procedure Set_User_Field

Syntax

Arguments

Description

The procedure Set_User_Field changes the value of the user-modifiable field for a specified task. If the task ID is not specified, the routine defaults to the current task. Either an Integer'Size value (via User_Field_t) or an Address'Size value (via User_Field2_t) can be stored in the task's User_Field. The Apex runtime does not use the User_Field.

function Start_Program

Syntax

Arguments

Description

The function Start_Program starts separately linked programs identified by their link block and enables concurrent execution of those programs. This function takes the parameter Link_Block_Address, which specifies the address of the Link_Block for the program to be started. It returns the ID of the just started program. Note that the Ada Program_ID and not the OS program or process ID is returned. This function assumes that the program to be started has previously been loaded.

Each program has a main task and a set of tasks it creates. Tasks from all programs execute from the same run queue.

The kernel has a linked list of programs with each program pointing to a linked list of the program tasks. Tasks from all programs compete for CPU time, according to their priority.

Threaded Runtime

This service is supported only by the Rational Exec Microkernel on cross targets.

This service is provided for Rational Exec Microkernel. However, this service may have different semantics or may not be supported by other underlying threaded runtimes. Not supported by LynxOS.

procedure Suspend_Task

Syntax

Arguments

Description

Suspend_Task is used to suspend a task that is either currently running or ready-to-run. Note that this does not make the task uncallable.

Exceptions/Results

Threaded Runtime

For the Rational Exec Microkernel, Suspend_Task always returns Suspended (or no exception is raised). Each task has a suspend flag. Suspend_Task always sets the task suspend flag to True. If the task is on the run queue, it is removed. The task is inhibited from being placed on the run queue until it is resumed with the Resume_Task service.

The semantics of the Suspend_Task service are dependent on the underlying operating system. Suspend_Task is layered on Ada_Krn_I.Task_Suspend.

function Terminated

Syntax

Arguments

Description

The function Terminated returns the Boolean value of the P'Terminated attribute for the specified task. If the task is terminated, Terminated returns the Boolean value True. Under all other conditions, Terminated returns the Boolean value False. Referencing a nonexistent task or a task that has not yet been created yields indeterminate values

generic function V_ID

Syntax

Arguments

Description

This generic can be instantiated with a task type to create a function that returns the task identifier for any object of that task type. The resulting task identifier can be used as a parameter to the Suspend_Task and Resume_Task operations. V_ID is applicable only to tasks declared as types.

Example

The following code fragment declares a task type Data_Receiver and creates a function Receiver_ID, which returns a task identifier for a Data_Receiver:

The following code fragment uses the function Receiver_ID to obtain a task identifier for a task object, Data1, that is type Data_Receiver. The resulting task ID is used to resume the task.


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