[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

OpenVMS Debugger Manual
Previous Contents Index

16.3.4 Task Built-In Symbols

The debugger built-in symbols defined in Table 16-2 enable you to specify tasks in command procedures and command constructs.

Table 16-2 Task Built-In Symbols
Built-in Symbol Description
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept statement executes, the task that called the entry that is associated with the accept statement.
%NEXT_TASK The task after the visible task in the debugger's task list. The ordering of tasks is arbitrary but consistent within a single run of a program.
%PREVIOUS_TASK The task previous to the visible task in the debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

Examples using these task built-in symbols follow.

The following command displays the task ID of the visible task: 


DBG> EVALUATE %VISIBLE_TASK

The following command places the active task on hold: 


DBG> SET TASK/HOLD %ACTIVE_TASK

The following command sets a breakpoint on line 25 that triggers only when task CHILD executes that line: 


DBG> SET BREAK %LINE 25 WHEN (%ACTIVE_TASK=CHILD)

The symbols %NEXT_TASK and %PREVIOUS_TASK enable you to cycle through the total set of tasks that currently exist. For example: 


DBG> SHOW TASK %VISIBLE_TASK; SET TASK/VISIBLE %NEXT_TASK
DBG> SHOW TASK %VISIBLE_TASK; SET TASK/VISIBLE %NEXT_TASK
   .
   .
   .
DBG> EXAMINE MONITOR_TASK
MOD\MONITOR_TASK: %TASK 2
DBG> WHILE %NEXT_TASK NEQ %ACTIVE DO (SET TASK %NEXT_TASK; SHOW CALLS)

16.3.4.1 Caller Task Symbol (Ada Only)

The symbol %CALLER_TASK is specific to Ada tasks. It evaluates to the task ID of the task that called the entry associated with the accept statement. Otherwise, it evaluates to %TASK 0. For example, %CALLER_TASK evaluates to %TASK 0 if the active task is not currently executing the sequence of statements associated with the accept statement.

For example, suppose a breakpoint has been set on line 46 of Example 16-2 (within an accept statement). The accept statement in this case is executed by task FATHER (%TASK 3) in response to a call of entry RENDEZVOUS by the main program (%TASK 1). Thus, when an EVALUATE %CALLER_TASK command is entered at this point, the result is the task ID of the calling task, the main program: 


DBG> EVALUATE %CALLER_TASK
%TASK 1
DBG>

When the rendezvous is the result of an AST entry call, %CALLER_TASK evaluates to %TASK 0 because the caller is not a task.

16.4 Displaying Information About Tasks

To display information about one or more tasks of your program, use the SHOW TASK command.

The SHOW TASK command displays information about existing (nonterminated) tasks. By default, the command displays one line of information about the visible task.

Section 16.4.1 and Section 16.4.2 describe the information displayed by a SHOW TASK command for POSIX Threads and Ada tasks, respectively.

16.4.1 Displaying Information About POSIX Threads Tasks

The command SHOW TASK displays information about all of the tasks of the program that currently exist (see Example 16-3).

Example 16-3 Sample SHOW TASK/ALL Display for POSIX Threads Tasks 

 (1)          (2)     (3)     (4)   (5)               (6)
 task id    state hold  pri substate        thread_object 
  %TASK    1 SUSP         12 Condition Wait  Initial thread 
  %TASK    2 SUSP         12 Mutex Wait      T_EXAMP\main\threads[0].field1 
  %TASK    3 SUSP         12 Delay           T_EXAMP\main\threads[1].field1 
  %TASK    4 SUSP         12 Mutex Wait      T_EXAMP\main\threads[2].field1 
* %TASK    5 RUN          12                 T_EXAMP\main\threads[3].field1 
  %TASK    6 READY        12                 T_EXAMP\main\threads[4].field1 
  %TASK    7 SUSP         12 Mutex Wait      T_EXAMP\main\threads[5].field1 
  %TASK    8 READY        12                 T_EXAMP\main\threads[6].field1 
  %TASK    9 TERM         12 Term. by alert  T_EXAMP\main\threads[7].field1 
DBG>

Key to Example 16-3:

  1. The task ID (see Section 16.3.3). The active task is marked with an asterisk (*) in the leftmost column.
  2. The current state of the task (see Table 16-3). The task in the RUN (RUNNING) state is the active task. Table 16-3 lists the state transitions possible during program execution.
  3. Whether the task has been put on hold with a SET TASK/HOLD command as explained in Section 16.5.1.
  4. The task priority.
  5. The current substate of the task. The substate helps indicate the possible cause of a task's state. See Table 16-4.
  6. A debugger path name for the task (thread) object or the address of the task object if the debugger cannot symbolize the task object.

Table 16-3 Generic Task States
Task State Description
RUNNING Task is currently running on the processor. This is the active task. A task in this state can make a transition to the READY, SUSPENDED, or TERMINATED state.
READY Task is eligible to execute and waiting for the processor to be made available. A task in this state can make a transition only to the RUNNING state.
SUSPENDED Task is suspended, that is, waiting for an event rather than for the availability of the processor. For example, when a task is created, it remains in the suspended state until it is activated. A task in this state can make a transition only to the READY or TERMINATED state.
TERMINATED Task is terminated. A task in this state cannot make a transition to another state.

Table 16-4 POSIX Threads Task Substates
Task Substate Description
Condition Wait Task is waiting on a POSIX Threads condition variable.
Delay Task is waiting at a call to a POSIX Threads delay.
Mutex Wait Task is waiting on a POSIX Threads mutex.
Not yet started Task has not yet executed its start routine.
Term. by alert Task has been terminated by an alert operation.
Term. by exc Task has been terminated by an exception.
Timed Cond Wait Task is waiting on a timed POSIX Threads condition variable.

The SHOW TASK/FULL command provides detailed information about each task selected for display. Example 16-4 shows the output of this command for a sample POSIX Threads task.

Example 16-4 Sample SHOW TASK/FULL Display for a POSIX Threads Task 

(1) task id    state hold  pri substate        thread_object 
 %TASK    4 SUSP         12 Delay           T_EXAMP\main\threads[1].field1 
(2)        Alert is pending 
          Alerts are deferred 
 
(3)        Next pc:           SHARE$CMA$RTL+46136 
          Start routine:     T_EXAMP\thread_action 
(4)        Scheduling policy: throughput 
 
(5)        Stack storage: 
          Bytes in use:          1288   (6) Base:    00334C00 
          Bytes available:      40185        SP:      003346F8 
          Reserved Bytes:       10752        Top:     00329A00 
          Guard Bytes:           4095 
 
(7)        Thread control block: 
          Size:                   293        Address: 00311B78 
 
(8)    Total storage:          56613 
DBG>

Key to Example 16-4:

  1. Identifying information about the task.
  2. Bulletin-type information about something unusual.
  3. Next execution PC value and start routine.
  4. Task scheduling policy.
  5. Stack storage information:
    • "Bytes in use:" the number of bytes of stack currently allocated.
    • "Bytes available:" the unused space in bytes.
    • "Reserved Bytes:" the storage allocated for handling stack overflow.
    • "Guard Bytes:" the size of the guard area or unwritable part of the stack.
  6. Minimum and maximum addresses of the task stack.
  7. Task (thread) control block information. The task value is the address, in hexadecimal notation, of the task control block.
  8. The total storage used by the task. Adds together the task control block size, the number of reserved bytes, the top guard size, and the storage size.

Figure 16-1 shows a task stack.

Figure 16-1 Diagram of a Task Stack

The SHOW TASK/STATISTICS command reports some statistics about all tasks in your program. Example 16-5 shows the output of the SHOW TASK/STATISTICS/FULL command for a sample program with POSIX Threads tasks. This information enables you to measure the performance of your program. The larger the number of total schedulings (also known as context switches), the more tasking overhead there is.

Example 16-5 Sample SHOW TASK/STAT/FULL Display for POSIX Threads Tasks 

task statistics 
    Total context switches:              0 
    Number of existing threads:          0 
    Total threads created:               0 
DBG>

16.4.2 Displaying Task Information About Ada Tasks

The SHOW TASK/ALL command displays information about all of the tasks of the program that currently exist---namely, tasks that have been created and whose master has not yet terminated (see Example 16-6).

Example 16-6 Sample SHOW TASK/ALL Display for Ada Tasks 

DBG>
SHOW TASK/ALL
      (1)        (2)    (3)   (4)     (5)                     (6)
task id    state hold  pri substate              thread_object   %TASK  1      READY        24                        main thread * %TASK  2      RUN          24                        1515464   %TASK  3      READY        19                        1519768   %TASK  4      SUSP         24 Timed Condition Wait   4932680
 
DBG>

Key to Example 16-6:

  1. The task ID (see Section 16.3.3). An asterisk indicates that the task is a visible task.
  2. The current state of the task (see Table 16-3). The task that is in the RUN (RUNNING) state is the active task. Table 16-3 lists the state transitions possible during program execution.
  3. Whether the task has been put on hold with a SET TASK/HOLD command as explained in Section 16.5.1. Placing a task on HOLD restricts the state transitions it can make after the program is subsequently allowed to execute.
  4. The task priority. Ada priorities range from 0 to 15. On Alpha systems, a task with an undefined priority competes with other tasks, as if having a mid-range priority (between 7 and 8). Ada provides the following two mechanisms for controlling task priorities:
    • Pragma PRIORITY A priority is associated with a task if a pragma PRIORITY appears in the corresponding task specification or in the outermost declarative part of a main subprogram.
    • Types and operations in the Ada package SET_TASK_PRIORITY. Ada allows task priorities to be changed dynamically at run-time to values of the subtype PRIORITY.
  5. The current substate of the task. The substate helps indicate the possible cause of a task's state. See Table 16-5.
  6. A debugger path name for the task object or the address of the task object if the debugger cannot symbolize the task object.

Table 16-5 Ada Task Substates
Task Substate Description
Abnormal Task has been aborted.
Accept Task is waiting at an accept statement that is not inside a select statement.
Activating Task is elaborating its declarative part.
Activating tasks Task is waiting for tasks it has created to finish activating.
Completed [abn] Task is completed due to an abort statement but is not yet terminated. In Ada, a completed task is one that is waiting for dependent tasks at its end statement. After the dependent tasks are terminated, the state changes to terminated.
Completed [exc] Task is completed due to an unhandled exception 1 but is not yet terminated. In Ada, a completed task is one that is waiting for dependent tasks at its end statement. After the dependent tasks are terminated, the state changes to terminated.
Completed Task is completed. No abort statement was issued and no unhandled exception 1 occurred.
Delay Task is waiting at a delay statement.
Dependents Task is waiting for dependent tasks to terminate.
Dependents [exc] Task is waiting for dependent tasks to allow an unhandled exception 1 to propagate.
Entry call Task is waiting for its entry call to be accepted.
Invalid state There is an error in the Compaq Ada Run-Time Library.
I/O or AST Task is waiting for I/O completion or some AST.
Not yet activated Task is waiting to be activated by the task that created it.
Select or delay Task is waiting at a select statement with a delay
alternative.
Select or terminate Task is waiting at a select statement with a terminate alternative.
Select Task is waiting at a select statement with no else, delay, or terminate alternative.
Shared resource Task is waiting for an internal shared resource.
Terminated [abn] Task was terminated by an abort statement.
Terminated [exc] Task was terminated because of an unhandled exception. 1
Terminated Task terminated normally.
Timed entry call Task is waiting in a timed entry call.
1 An unhandled exception is one for which there is no handler in the current frame or for which there is a handler that executes a raise statement and propagates the exception to an outer scope.

Figure 16-1 shows a task stack.

The SHOW TASK/FULL command provides detailed information about each task selected for display. Example 16-7 shows the output of this command for a sample Ada task.

Example 16-7 Sample SHOW TASK/FULL Display for an Ada Task 

(1) task id    state hold  pri substate     thread_object 
     %TASK 1    RUN         24               1515464 
 
(2)         Cancellation is enabled 
          
 
            Next pc:              (unknown) 
            Start routine:        1380128 
            Scheduling policy:    fifo        (real-time) 
 
(3)  Stack storage: 
            Bytes in use:          7069696      (4) Base:    00000000006BE000 
            Bytes available:      -4972544           SP:      0000000000000000 
            Reserved Bytes:              0           Top:     00000000004BE000 
            Guard Bytes:                 0 
 
(5)  Thread control block: 
          Size:                   5856               Address: 00000000006BF280 
 
(6)  Total storage:          2103008 
DBG>

Key to Example 16-7:

  1. Identifying information about the task.
  2. Rendezvous information. If the task is a caller task, it lists the entries for which it is queued. If the task is to be called, it gives information about the kind of rendezvous that will take place and lists the callers that are currently queued for any of the task's entries.
  3. Stack storage information:
    • "Bytes in use:" the number of bytes of stack currently allocated.
    • "Bytes available:" the unused space in bytes.
    • "Reserved Bytes:" the storage allocated for handling stack overflow.
    • "Guard Bytes:" the size of the guard area or unwritable part of the stack.
  4. Minimum and maximum addresses of the task stack.
    • "SP:" Stack Pointer indicates a location in the stack memory.
    • "TOP:" indicates the last allocated stack location.
  5. Task (thread) control block information. The task value is the address, in hexadecimal notation, of the task control block.
  6. The total storage used by the task. Adds together the task control block size, the number of reserved bytes, the top guard size, and the storage size.

The SHOW TASK/STATISTICS command reports some statistics about all tasks in your program. Example 16-8 shows the output of the SHOW TASK/STATISTICS/FULL command for a sample Ada tasking program on a VAX system. This information enables you to measure the performance of your program. The larger the number of total schedulings (also known as context switches), the more tasking overhead there is.

Example 16-8 Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks 

DBG> SHOW TASK/STATISTICS/FULL 
task statistics 
 Total context switches:         0 
 Number of existing threads:     6 
 Total threads created:          4 
DBG>

16.5 Changing Task Characteristics

To modify a task's characteristics or the tasking environment while debugging, use the SET TASK command, as shown in the following table:
Command Description
SET TASK/ACTIVE Makes a specified task the active task; not for POSIX Threads (on OpenVMS Alpha or Integrity servers) or Ada on OpenVMS Alpha and Integrity servers (see Section 16.3.1).
SET TASK/VISIBLE Makes a specified task the visible task (see Section 16.3.1).
SET TASK/ABORT Requests that a task be terminated at the next allowed opportunity. The exact effect depends on the current event facility (language dependent). For Ada tasks, this is equivalent to executing an abort statement.
SET TASK/PRIORITY Sets a task's priority. The exact effect depends on the current event facility (language dependent).
SET TASK/RESTORE Restores a task's priority. The exact effect depends on the current event facility (language dependent).
SET TASK/[NO]HOLD Controls task switching (task state transitions, see Section 16.5.1).

For more information, see the SET TASK command description.

Previous Next Contents Index