![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 OverviewDescription
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.
Types
Table 26 lists the types in package V_Xtasking.
Subtypes
Table 27 lists the subtypes in package V_Xtasking.
Constants
Table 28 lists the constants in package V_Xtasking.
Exceptions
Table 29 lists the exceptions in package V_Xtasking.
Package Specification
with Ada_Krn_Defs; with System; package V_Xtasking is
pragma suppress(ALL_Checks);
Null_Task_Name: constant system.task_id := system.No_Task_Id; type os_task_id is new Ada_Krn_Defs.krn_task_id; Null_Os_Task_Name: constant os_task_id := os_task_id(Ada_Krn_Defs.No_Krn_Task_Id);
type os_program_id is new ADA_Krn_Defs.krn_program_id; NULL_OS_Program_NAME: constant os_program_id := os_program_id(ADA_Krn_Defs.NO_Krn_Program_ID);
type task_storage_id is private; NO_Task_STORAGE_ID: constant task_storage_id;
type callout_event_t is new ADA_Krn_Defs.callout_event_t;
subtype user_field_t is integer;
subtype user_field2_t is System.address;
INVALID_SUSPEND : exception; INVALID_Resume : exception;
UNEXPECTED_V_Xtasking_ERROR : exception;
type xtasking_result is (SUSPENDED, RESUMED, NOT_SUSPENDED, NOT_RESUMED);
function ID(os_task_name : in os_task_id) return system.task_id;
function ID(os_program_name: in os_program_id) return system.program_id;
function ID(task_address : in system.task_id) return system.task_id; pragma Inline_Only(ID);
function OS_ID(task_name : in system.task_id) return os_task_id;
generic type task_type is limited private; function V_ID(task_object : in task_type) return system.task_id; pragma Inline_Only(V_ID);
function OS_ID(program_name : in system.program_id) return os_program_id; pragma Inline_Only(OS_ID);
function Current_Task return system.task_id; pragma Inline_Only(Current_Task);
procedure Resume_Task (task_name : in system.task_id); procedure Resume_Task (task_name : in system.task_id; result : out xtasking_result); pragma Inline_Only(Resume_Task); procedure SUSPEND_Task (task_name : in system.task_id); procedure SUSPEND_Task (task_name : in system.task_id; result : out xtasking_result); pragma Inline_Only(SUSPEND_Task);
function Current_Priority (task_name : in system.task_id := Current_Task) eturn system.priority; pragma Inline_Only(Current_Priority);
procedure Set_PRIORITY (new_priority : in system.priority; task_name : in system.task_id := Current_Task); pragma Inline_Only(Set_PRIORITY);
function Current_TIME_SLICE (task_name : in system.task_id := Current_Task) return duration; pragma Inline_Only(Current_TIME_SLICE);
procedure Set_TIME_SLICE (new_interval : in duration; task_name : in system.task_id := Current_Task); pragma Inline_Only(Set_TIME_SLICE);
function Current_User_Field (task_name : in system.task_id := Current_Task) return user_field_t; function Current_User_Field (task_name : in system.task_id := Current_Task) return user_field2_t; pragma Inline_Only(Current_User_Field);
procedure Set_User_Field (new_value : in user_field_t; task_name : in system.task_id := Current_Task); procedure Set_User_Field (new_value : in user_field2_t; task_name : in system.task_id := Current_Task); pragma Inline_Only(Set_User_Field);
function Callable (task_name : in system.task_id) return boolean; pragma Inline_Only(Callable);
function Terminated (task_name : in system.task_id) return boolean; pragma Inline_Only(Terminated);
function Current_TIME_Slicing_Enabled return boolean; pragma Inline_Only(Current_TIME_Slicing_Enabled);
procedure Set_TIME_Slicing_Enabled (new_value : in boolean := True); pragma Inline_Only(Set_TIME_Slicing_Enabled);
function Current_Exit_Disabled return boolean; pragma Inline_Only(Current_Exit_Disabled);
procedure Set_EXIT_DISABLED (new_value : in boolean := True); pragma Inline_Only(Set_EXIT_DISABLED);
function START_Program (link_block_address : in system.address; key : in system.address := system.address'ref(2); terminate_callout : in system.address := system.NO_ADDR) return system.program_id; pragma Inline_Only(START_Program);
function Current_Program return system.program_id; pragma Inline_Only(Current_Program);
function Get_Program(task_name : in system.task_id) return system.program_id; pragma Inline_Only(Get_Program);
procedure Terminate_Program (status : in integer; program_name : in system.program_id := Current_Program); pragma Inline_Only(Terminate_Program);
function Get_Program_Key (program_name : in system.program_id := Current_Program) return system.address; pragma Inline_Only(Get_Program_Key);
procedure Set_IS_SERVER_Program; pragma Inline_Only(Set_IS_SERVER_Program);
procedure INTER_Program_CALL (procedure_program : in system.program_id; procedure_address : in system.address; argument : in system.address); pragma Inline_Only(INTER_Program_CALL);
procedure INSTALL_CALLOUT (event : in callout_event_t; proc : in system.address); pragma Inline_Only(INSTALL_CALLOUT);
function Allocate_Task_Storage (size : in natural) return task_storage_id; pragma Inline_Only(Allocate_Task_Storage);
function Get_Task_Storage (task_name : in system.task_id; storage_id : in task_storage_id) return system.address; pragma Inline_Only(Get_Task_Storage);
function Get_Task_Storage2 (os_task_name : in os_task_id; storage_id : in task_storage_id) return system.address; pragma Inline_Only(Get_Task_Storage2);
procedure Disable_PREEMPTION; pragma Inline_Only(Disable_PREEMPTION); procedure Enable_PREEMPTION; pragma Inline_Only(Enable_PREEMPTION);
procedure Disable_Task_Complete; procedure Enable_Task_Complete; pragma Inline_Only(Disable_Task_Complete); pragma Inline_Only(Enable_Task_Complete); function Current_Fast_Rendezvous_Enabled return boolean; pragma Inline_Only(Current_Fast_Rendezvous_Enabled);
procedure Set_Fast_Rendezvous_Enabled (new_value : in boolean); pragma Inline_Only(Set_Fast_Rendezvous_Enabled);
private type task_storage_id is new ADA_Krn_Defs.task_storage_id; NO_Task_STORAGE_ID: constant task_storage_id := task_storage_id(ADA_Krn_Defs.NO_Task_STORAGE_ID); end V_Xtasking;
Procedures and Functions in Package V_Xtaskingfunction Allocate_Task_Storage
Syntax
function Allocate_Task_Storage (size : in natural) return task_storage_id; pragma Inline_Only(Allocate_Task_Storage);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
- Storage_Error
Raised if there is not enough memory in the task control block for the task storage. The configuration parameter Task_Storage_Size defines the size of the storage area set aside in the control block for each task. Each allocation from this area is aligned on a 4- or 8- byte boundary (the alignment is CPU dependent).
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
function Callable (task_name : in system.task_id) return boolean; pragma Inline_Only(Callable);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
function Current_Exit_Disabled return boolean; pragma Inline_Only(Current_Exit_Disabled);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
function Current_Fast_Rendezvous_Enabled return boolean; pragma Inline_Only(Current_Fast_Rendezvous_Enabled);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
function Current_Priority (task_name : in system.task_id := Current_Task) return system.priority; pragma Inline_Only(Current_Priority);Arguments
- task_name
D of the task whose priority is to be returned to the caller. If no task name is specified, task_name defaults to the current task.
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
function Current_Program return system.program_id; pragma Inline_Only(Current_Program);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
function Current_Task return system.task_id; pragma Inline_Only(Current_Task);Description
This function returns the task ID of the current task.
Example
The following call suspends the currently running task:
V_Xtasking.SUSPEND_Task(V_Xtasking.Current_Task);
function Current_Time_Slice
Syntax
function Current_Time_Slice (task_name : in system.task_id := Current_Task) return duration; pragma Inline_Only(Current_Time_Slice);Arguments
- task_name
ID of the task whose time slice interval is returned. If no task_name is specified, the routine defaults to the current task.
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
function Current_Time_Slicing_Enabled return boolean; pragma Inline_Only(Current_Time_Slicing_Enabled)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
function Current_User_Field (task_name : in system.task_id := Current_Task) return user_field_t; function Current_User_Field (task_name : in system.task_id := Current_Task) return user_field2_t; pragma Inline_Only(Current_User_Field);Arguments
- task_name
ID of the task for which the value of the user-modifiable field is returned. The default is the current task.
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
procedure Disable_Preemption; pragma Inline_Only(Disable_Preemption);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
procedure Disable_Task_Complete; pragma Inline_Only(Disable_Task_Complete);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:
Disable_Task_Complete; acquire_resource; use_resource; release_resource; Enable_Task_Complete;
Warning: This procedure must always be paired with procedure Enable_Task_Complete.
procedure Enable_Preemption
Syntax
procedure Enable_Preemption; pragma Inline_Only(Enable_Preemption);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
procedure Enable_Task_Complete; pragma Inline_Only(Enable_Task_Complete);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:
Disable_Task_Complete; acquire_resource; use_resource; release_resource; Enable_Task_Complete;
Warning: This procedure must always be paired with procedure Disable_Task_Complete.
function Get_Program
Syntax
function Get_Program (task_name : in system.task_id) return system.program_id; pragma Inline_Only(Get_Program);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
function Get_Program_Key (program_name: in system.program_id := Current_Program) return system.address; pragma Inline_Only(Get_Program_Key);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
function Get_Task_Storage (task_name : in system.task_id) storage_id : in task_storage_id) return system.address; pragma Inline_Only(Get_Task_Storage);Arguments
- storage_id
Value returned by a previous call to Allocate_Task_Storage. It is applicable only to tasks in the program where the Allocate_Task_Storage service is called from.
- task_name
ID of the task for which the address of the task storage area is returned.
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
function Get_Task_Storage2 (os_task_name : in os_task_id) storage_id : in task_storage_id) return system.address; pragma Inline_Only(Get_Task_Storage2);Arguments
- os_task_name
OS identifier of the task for which the address of the task storage area is returned.
- storage_id
Value returned by a previous call to Allocate_Task_Storage. It is applicable only to tasks in the program where the Allocate_Task_Storage service is called from.
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
function Id (task_address : in system.task_id) return task_id; pragma Inline_Only(ID);
function Id (os_task_name : in os_task_id) return system.task_id; pragma Inline_Only(Id);
function Id (os_program_name : in os_program_id) return system.program_id; pragma Inline_Only(Id);Arguments
- os_program_name
- os_task_name
- task_address
Address of a task obtained by applying the 'Task_ID attribute to a task name.
The T'Address attribute is the starting address of the task body machine code. Therefore, the type of the Task_Address parameter has changed from System.Address to System.Task_ID.
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:
V_Xtasking.Resume_Task(V_Xtasking.ID(OTHER_Task'task_id));
Error Results
procedure Install_Callout
Syntax
procedure Install_Callout (event : in callout_event_t; proc : in system.address); pragma Inline_Only(INSTALL_CALLOUT)Arguments
- event
Program, task, or idle event at which time the installed procedure is called.
- proc
Address of the procedure to be called. The Exit_Event or Unexpected_Exit_Event callout procedures are called as follows:
procedure exit_callout_proc (status : in integer); -- main subprogram -- return status
The Program_Switch_Event callout procedure is called as follows:
procedure program_switch_callout_proc (new_os_program_name : in os_program_id; key : in address);
Note: This procedure is called with the OS Program_Name and not the Ada Program_Name. Use V_Xtasking.ID(os_program_name) to get the Ada Program_ID.
The Task_Create_Event, Task_Switch_Event, and Task_Complete_Event callout procedures are called as follows:
procedure task_callout_proc (os_task_name : in os_task_id);
Note: This procedure is called with the OS Task_Name and not the Ada Task_Name. You can use V_Xtasking.ID(os_task_name) to get the Ada Task_ID.
The Idle_Event callout procedure is called as follows:
procedure idle_callout_proc;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:
- Exit_Event
Called when the program exits or terminates itself. Not called when the program is terminated from another program. Still called when the Unexpected_Exit_Event callout is called.
- Idle_Event
Called whenever there are not any ready-to-run tasks.
- Program_Switch_Event
Called before switching to a task that resides in a program different from the current program. Called for all program switches, not just switches to and from the program containing the callout. Also called before switching to the kernel program's IDLE task. However, not called when a procedure in another program is called via V_Xtasking.Inter_Program_Call.
- Task_Complete_Event
Called whenever any task in the callout program completes or is aborted.
- Task_Create_Event
Called whenever a task is created in the program containing the callout. Since the Task_Create_Event callout can be installed after numerous tasks have already been created, the Install_Callout service loops through all existing tasks invoking the just installed. Task_Create_Event callout
- Task_Switch_Event
Called before switching to a different task in the same program. For a program switch, the Task_Switch_Event callout is called with the os_task_name parameter set to Null_Os_Task_Name.
- Unexpected_Exit_Event
Called when the program is abandoned because of an unhandled Ada exception.
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
procedure Inter_Program_Call (procedure_program : in system.program_id; procedure_address : in system.address; argument : in system.address); pragma Inline_Only(Inter_Program_Call);Arguments
- argument
The only parameter passed to the called procedure.
- procedure_address
Address of the called procedure.
- procedure_program
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:
procedure called_procedure(argument: system.address);
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
function Os_Id (task_name : in system.task_id) return os_task_id; pragma Inline_Only(OS_ID); function Os_Id (program_name : in system.program_id) return os_program_id; pragma Inline_Only(Os_Id);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
procedure Resume_Task (task_name : in system.task_id); pragma Inline_Only(Resume_Task); procedure Resume_Task (task_name : in system.task_id; result : out xtasking_result) pragma Inline_Only(Resume_Task);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
- Invalid_Resume/Not_Resumed
Task is not resumed (Not used with Rational Exec Microkernel).
- /Resumed
The result value Resumed is returned if the task is resumed.
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
procedure Set_Exit_Disabled (new_value : in boolean := True); pragma Inline_Only(Set_Exit_Disabled);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
procedure Set_Fast_Rendezvous_Enabled (new_value : boolean); pragma Inline_Only(Set_Fast_Rendezvous_Enabled);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
procedure Set_Is_Server_Program; pragma Inline_Only(Set_Is_Server_Program);
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
procedure Set_Priority (new_priority : in system.priority; task_name : in system.task_id := Current_Task); pragma Inline_Only(Set_Priority);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
procedure Set_Time_Slice (new_interval : in duration; task_name : in system.task_id := Current_Task); pragma Inline_Only(Set_Time_Slice);
Arguments
- new_interval
New time slice duration. An interval of 0.0 seconds disables time slicing for the task.
- task_name
ID of the task that is to have the time slice interval changed. The default is the current task.
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
procedure Set_Time_Slicing_Enabled (new_value : in boolean := True); pragma Inline_Only(Set_Time_Slicing_Enabled);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
procedure Set_User_Field (new_value : in user_field_t; task_name : in system.task_id := Current_Task); procedure Set_User_Field (new_value : in user_field2_t; task_name : in system.task_id := Current_Task); pragma Inline_Only(Set_User_Field);Arguments
- new_value
New value to be written to the user-modifiable field.
- task_name
ID of the task to have the user-modifiable field changed. The default is the current task.
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
function Start_Program (link_block_address : in system.address; key : in system.address := system.address'ref(2); terminate_callout : in system.address := system.NO_ADDR); return system.program_id; pragma Inline_Only(Start_Program);Arguments
- key
User-defined values are stored in the new program control block. This key is passed to the Program_Switch_Event callouts. The key may be obtained by routines in the new program via the Get_Program_Key service. One use for the key is to have it point to a list of program arguments. The value for the main program key is System.Address'Ref(0). For cross targets, the kernel program has a predefined key of System.Address'Ref(1).
- link_block_address
Link_Block address of the program to be started.
- terminate_callout
Address of the procedure to be called when the program exits or is terminated. A value of No_Addr indicates no callout. The callout procedure is called as follows:
procedure terminate_callout_proc (os_program_name : in os_program_id; key : in address);
Note that this procedure is called with the OS Program_Name, not the Ada Program_Name. Use V_Xtasking.ID(os_program_name) to get the Ada Program_ID.
Terminate_Callout_Proc must be compiled with stack limit checking suppressed. The Program_Switch_Event callout is not called before the Terminate_Callout_Proc is called.
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
procedure Suspend_Task (task_name : in system.task_id); pragma Inline_Only(Suspend_Task); procedure Suspend_Task (task_name : in system.task_id; result : out xtasking_result); pragma Inline_Only(Suspend_Task);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
- Invalid_Suspend/Not_Suspended
Task is not suspended (Not used with Rational Exec Microkernel).
- Suspended
The result value Suspended is returned if the task is suspended.
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
function Terminated (task_name : in system.task_id) return boolean; pragma Inline_Only(Terminated);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
generic type task_type is limited private; function V_ID (task_object : in task_Type) return task_id; pragma INLINE_ONLY(V_ID);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:
task type Data_Receiver; function Receiver_Id is new V_Xtasking.V_ID(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.
V_Xtasking.Resume_Task(Receiver_ID(Data1);
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2003, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |