OpenVMS Debugger Manual

Document revision date: 30 March 2001

OpenVMS Debugger Manual

Contents

Index

Identifying information about the task.
Bulletin-type information about something unusual.
Next execution PC value and start routine.
Task scheduling policy.
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.
Minimum and maximum addresses of the task stack.
Task (thread) control block information. The task value is the address, in hexadecimal notation, of the task control block.
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 17-1 shows a task stack.

Figure 17-1 Diagram of a Task Stack

The SHOW TASK/STATISTICS command reports some statistics about all tasks in your program. Example 17-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 17-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>

17.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 17-6).

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

(1) (2) (3) (4) (5) (6) task id pri hold state substate task object * %TASK 1 7 RUN SHARE$ADARTL+130428 %TASK 2 7 HOLD SUSP Accept TASK_EXAMPLE.MOTHER+4 %TASK 4 7 SUSP Entry call TASK_EXAMPLE.FATHER_TYPE$TASK_BODY.CHILD+4 %TASK 3 6 READY TASK_EXAMPLE.MOTHER) DBG>

Key to Example 17-6:

The task ID (see Section 17.3.3). An asterisk indicates that the task is a visible task.
The task priority. Ada priorities range from 0 to 15.
On VAX processors, a task is created with a default priority of 7 unless another value is specified with the pragma PRIORITY.
On Alpha processors, if time slicing is disabled, a task is created with a default prioity of 7; if time slicing is enabled, then a task is created with an approximate midrange value (unless the pragma PRIORITY is specified).
Whether the task has been put on hold with a SET TASK/HOLD command as explained in Section 17.5.1. Placing a task on HOLD restricts the state transitions it can make after the program is subsequently allowed to execute.
The current state of the task (see Table 17-3). The task that is in the RUN (RUNNING) state is the active task. Table 17-3 lists the state transitions possible during program execution.
The current substate of the task. The substate helps indicate the possible cause of a task's state. See Table 17-5.
A debugger path name for the task object or the address of the task object if the debugger cannot symbolize the task object.

Table 17-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 ¹ 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 ¹ 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 ¹ 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. ¹

Terminated Task terminated normally.

Timed entry call Task is waiting in a timed entry call.

**Table 17-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 ¹ 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 ¹ 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 ¹ 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. ¹
Terminated	Task terminated normally.
Timed entry call	Task is waiting in a timed entry call.

¹ 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 17-1 shows a task stack.

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

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

(1) task id pri hold state substate task object * %TASK 2 7 RUN TASK_EXAMPLE.MOTHER+4 (2) Waiting entry callers: Waiters for entry BOGUS: %TASK 4, type: CHILD (3) Task type: FATHER_TYPE Created at PC: TASK_EXAMPLE.%LINE 14+22 Parent task: %TASK 1 Start PC: TASK_EXAMPLE.FATHER_TYPE$TASK_BODY (4) Task control block: (5) Stack storage (bytes): Task value: 490816 RESERVED_BYTES: 10640 Entries: 3 TOP_GUARD_SIZE: 5120 Size: 1488 STORAGE_SIZE: 30720 (6) Stack addresses: Bytes in use: 456 Top address: 001EB600 Base address: 001F2DFC (7) Total storage: 47968 DBG>

Key to Example 17-7:

Identifying information about the task.
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.
Task context information.
Task control block information. The task value is the address, in decimal notation, of the task control block.
Stack storage information:
- RESERVED_BYTES gives the storage allocated by the Ada Run-Time Library for handling stack overflow.
- TOP_GUARD_SIZE gives the storage allocated for guard pages, which provide protection against storage overflow during task execution.
  On VAX processors, you can specify the number of bytes to be allocated as guard pages with the Compaq Ada pragmas TASK_STORAGE and MAIN_STORAGE; the number shown by the debugger is the number of bytes allocated (the pragma value is rounded up to an integral number of pages, as necessary). For more information about these pragmas and the top guard storage area, see the Compaq Ada documentation.
  On Alpha processors, you can specify the number of bytes to be allocated as guard pages with the Compaq Ada pragmas TASK_STORAGE; the number shown by the debugger is the number of bytes allocated (the pragma value is rounded up to an integral number of pages, as necessary). For more information about these pragmas and the top guard storage area, see the Compaq Ada documentation.
- STORAGE_SIZE gives the storage allocated for the task activation.
  On VAX processors, you can specify the number of bytes to be allocated with the T'STORAGE_SIZE representation clause or in the Ada pragma MAIN_STORAGE; the number shown by the debugger is the number of bytes allocated (the value specified is rounded up to an integral number of pages, as necessary). For more information about this representation clause and pragma and about the task activation (working) storage area, see the Compaq Ada documentation.
  On Alpha processors, you can specify the number of bytes to be allocated with the T'STORAGE_SIZE representation clause; the number shown by the debugger is the number of bytes allocated (the value specified is rounded up to an integral number of pages, as necessary). For more information about this representation clause and pragma and about the task activation (working) storage area, see the Compaq Ada documentation.
- "Bytes in use:" gives the number of bytes of stack currently allocated.
Stack addresses of the task stack.
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 17-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 17-8 Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks (VAX Example)

task statistics Entry calls = 4 Accepts = 1 Selects = 2 Tasks activated = 3 Tasks terminated = 0 ASTs delivered = 4 Hibernations = 0 Total schedulings = 15 Due to readying a higher priority task = 1 Due to task activations = 3 Due to suspended entry calls = 4 Due to suspended accepts = 1 Due to suspended selects = 2 Due to waiting for a DELAY = 0 Due to scope exit awaiting dependents = 0 Due to exception awaiting dependents = 0 Due to waiting for I/O to complete = 0 Due to delivery of an AST = 4 Due to task terminations = 0 Due to shared resource lock contention = 0 DBG>

17.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 VAX) or Ada on OpenVMS Alpha (see Section 17.3.1).
SET TASK/VISIBLE	Makes a specified task the visible task (see Section 17.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 17.5.1).
SET TASK/TIME_SLICE	Controls the time slice value or disable time slicing (see Section 17.5.2); supported for VAX Ada only, and not with POSIX Threads.

For more information, see the SET TASK command description.

17.5.1 Putting Tasks on Hold to Control Task Switching

Task switching might be confusing when you are debugging a program. Placing a task on hold with the SET TASK/HOLD command restricts the state transitions the task can make once the program is subsequently allowed to execute.

A task placed on hold can enter any state except the RUNNING state. If necessary, you can force it into the RUNNING state by using the SET TASK/ACTIVE command.

The SET TASK/HOLD/ALL command freezes the state of all tasks except the active task. You can use this command in combination with the SET TASK/ACTIVE command, to observe the behavior of one or more specified tasks in isolation, by executing the active task with the STEP or GO command, and then switching execution to another task with the SET TASK/ACTIVE command. For example:

DBG> SET TASK/HOLD/ALL DBG> SET TASK/ACTIVE %TASK 1 DBG> GO . . . DBG> SET TASK/ACTIVE %TASK 3 DBG> STEP . . .

When you no longer want to hold a task, use the SET TASK/NOHOLD command.

17.5.2 Debugging Programs That Use Time Slicing (VAX Ada Only)

Tasking programs that use time slicing are difficult to debug because time slicing makes the relative behavior of tasks asynchronous. Without time slicing, task execution is determined solely by task priority; task switches are predictable and the behavior of the program is repeatable from one run to the next. With time slicing, task priorities still govern task switches, but tasks of the same priority also take turns executing for a specified period of time. Thus, time slicing causes tasks to execute more independently from each other, and the behavior of a program that uses time slicing might not be repeatable from one run of the program to the next.

The SET TASK/TIME_SLICE=t command (supported for VAX Ada only) enables you to specify a new time slice or disable time slicing (with SET TASK/TIME_SLICE=0.0). Thus, you can tune the execution of your tasking programs or diagnose problems that depend on the order in which tasks execute.

Note

The SET TASK/TIME_SLICE command is supported for VAX Ada only, and not for VAX Ada with POSIX Threads. If you use the command in an unsupported context, the debugger issues the following error message:

%DEBUG-E-NOTIMSLI, time slice modification not supported by this event facility

Note that there is an interaction between time slicing and the debugger watchpoint implementation. When you set watchpoints, the debugger might automatically increase the value of the time-slice interval to 10.0 seconds. Slowing the time-slice rate prevents some problems.

17.6 Controlling and Monitoring Execution

The following sections explain how to do the following functions:

Set task-specific and task-independent eventpoints (breakpoints, tracepoints, and so on)
Set breakpoints and tracepoints on task locations specific to POSIX Threads
Set breakpoints and tracepoints on task locations specific to Ada
Monitor task events with the SET BREAK/EVENT or SET TRACE/EVENT commands

17.6.1 Setting Task-Specific and Task-Independent Debugger Eventpoints

An eventpoint is an event that you can use to return control to the debugger. Breakpoints, tracepoints, watchpoints, and the completion of STEP commands are eventpoints.

A task-independent eventpoint can be triggered by the execution of any task in a program, regardless of which task is active when the eventpoint is set. Task-independent eventpoints are generally specified by an address expression such as a line number or a name. All watchpoints are task-independent eventpoints. The following are examples of setting task-independent eventpoints:

DBG> SET BREAK COUNTER DBG> SET BREAK/NOSOURCE %LINE 55, CHILD$TASK_BODY DBG> SET WATCH/AFTER=3 KEEP_COUNT

A task-specific eventpoint can be set only for the task that is active when the command is entered. A task-specific eventpoint is triggered only when that same task is active. For example, the STEP/LINE command is a task-specific eventpoint: other tasks might execute the same source line and not trigger the event.

If you use the SET BREAK, SET TRACE, or STEP commands with the following qualifiers, the resulting eventpoints are task specific:

/BRANCH
/CALL
/INSTRUCTION
/LINE
/RETURN
/VECTOR_INSTRUCTION (VAX only)

Any other eventpoints that you set with those commands and any eventpoints that you set with the SET WATCH command are task independent. The following are examples of setting task-specific eventpoints:

DBG> SET BREAK/INSTRUCTION DBG> SET TRACE/INSTRUCTION/SILENT DO (EXAMINE KEEP_COUNT) DBG> STEP/CALL/NOSOURCE

You can conditionalize eventpoints that are normally task-independent to make them task specific. For example:

DBG> SET BREAK %LINE 11 WHEN (%ACTIVE_TASK=FATHER)

17.6.2 Setting Breakpoints on POSIX Threads Tasking Constructs

You can set a breakpoint on a thread start routine. The breakpoint will trigger just before the start routine begins execution. In Example 17-1, this type of breakpoint is set as follows:

DBG> SET BREAK worker_routine

Unlike Ada tasks, you cannot specify the body of a POSIX Threads task by name but the start routine is similar.

Specifying a WHEN clause with the SET BREAK command ensures that you catch the point at which a particular thread begins execution. For example:

DBG> SET BREAK worker_routine - _DBG> WHEN (%ACTIVE_TASK = %TASK 4)

In Example 17-1, this conditional breakpoint will trigger when the second worker thread begins executing its start routine.

Other useful places to set breakpoints are just prior to and immediately after condition waits, joins, and locking of mutexes. You can set such breakpoints by specifying either a line number or the routine name.

Contents

Index

privacy and legal statement

4538PRO_036.HTML