Revised the structural overview disagram.

Introduced the notion of generating and scheduling parents.
Incremented version to 2.001.

Author: ariel-rw

figures/ompd-structural-overview.docx

@@ -411,21 +411,63 @@ \subsection{Task Handles}
 \refdef{\texttt{ompd\_release\_task\_handle}}{release-task-handle:def}.
 
 \paragraph{Retrieve the handle for an enclosing task.}
-The  debugger uses \verb|ompd_get_ancestor_task_region| to obtain
-a pointer to the task handle for the task region enclosing the
-task region specified by \verb|task_handle|.
+The OMPD API includes operations to obtain the handle of the
+parent of a task represented by a given task handle.
+There are two notions of parenthood.
+The \emph{scheduling} parent task is the task that was active
+when the child task was scheduled to run.
+The \emph{generating} is the task that encountered the OpenMP
+that caused the child task to be created.
+
+The generating and scheduling parents need not be the same.
+This might happen if the thread executing a task encounters
+an OpenMP construct.
+When this happens, the thread will enter the runtime.
+The runtime will set up the tasks to implement the OpenMP program
+construct, and then call its schedular to choose a task to
+execute.
+If the scheduler chooses a task other than one of these newly
+created tasks to run, the scheduling parent of the selected task
+will not be the same as its generating parent.
+The former is the task that the thread was executing most recently,
+and from which it entered the runtime.
+The later is the task which encountered the OpenMP construct
+it is executing.
+
+The  debugger uses \verb|ompd_get_generating_ancestor_task_region| to obtain
+a pointer to the task handle for the task that encountered the OpenMP
+construct which caused the task represented by \verb|task_handle|
+to be created.
 This call is meaningful only if the thread executing the task specified by
 \verb|task_handle|  is stopped.
 \begin{quote}
 \begin{lstlisting}
-ompd_rc_t  ompd_get_ancestor_task_region (
+ompd_rc_t  ompd_get_generating_ancestor_task_region (
   ompd_task_handle_t         *task_handle,                          /* IN */
   ompd_task_handle_t        **parent_task_handle                   /* OUT */
 );
 \end{lstlisting}
 \end{quote}
-\labeldef{get-ancestor-task-region:def}
-The task handle must be released by calling
+\labeldef{get-generating-ancestor-task-region:def}
+
+The \verb|ompd_get_scheduling_ancestor_task_region| returns the
+scheduling parent of the task represented \verb|task_handle|.
+The scheduling parent task is the OpenMP task that was active when
+the child task was scheduled.
+
+This call is meaningful only if the thread executing the task specified by
+\verb|task_handle|  is stopped.
+\begin{quote}
+\begin{lstlisting}
+ompd_rc_t  ompd_get_scheduling_ancestor_task_region (
+  ompd_task_handle_t         *task_handle,                          /* IN */
+  ompd_task_handle_t        **parent_task_handle                   /* OUT */
+);
+\end{lstlisting}
+\end{quote}
+\labeldef{get-scheduling-ancestor-task-region:def}
+
+The parent task handle must be released by calling
 \refdef{\texttt{ompd\_release\_task\_handle}}{release-task-handle:def}.
 
 \paragraph{Retrieve implicit task handle for a parallel region.}
@@ -538,4 +580,4 @@ \subsection{Task Handles}
 The contents of the strings returned for task handles
 which compare as equal with
 \refdef{\texttt{ompd\_task\_handle\_compare}}{task-handle-compare:def}
-must be the same.
+must be the same.

figures/ompd-structural-overview.pdf

@@ -42,9 +42,7 @@ \subsection{Parallel Region Settings}
 \end{quote}
 \labeldef{get-active-level:def}
 
-\subsection{OMPT Parallel Region Inquiry Analogues}
-
-\paragraph{Parallel Function Entry Point}
+\subsection{Parallel Function Entry Point}
 
 The \texttt{ompd\_get\_parallel\_function} returns the
 entry point of the code that corresponds to the body of
@@ -58,4 +56,4 @@ \subsection{OMPT Parallel Region Inquiry Analogues}
 );
 \end{lstlisting}
 \end{quote}
-\labeldef{get-parallel-function:def}
+\labeldef{get-parallel-function:def}

ompd-tr.pdf

@@ -269,7 +269,7 @@ \subsection{Stack Unwinding}
 semantics of the \verb|reenter_runtime_addr| field.)
 \end{notes}
 %
-The debugger can unwind a thread's logical stack by getting the
+The debugger can unwind a thread's stack by getting the
 thread's current task using
 \refdef{\texttt{ompd\_get\_top\_task\_region}}{get-top-task-region:def}.
 \begin{notes}
@@ -280,12 +280,10 @@ \subsection{Stack Unwinding}
 Using the task handle, the debugger can find the thread's exit and
 reentry stack frame addresses using \texttt{ompd\_get\_task\_frame}.
 %
-It can then use
-\refdef{\texttt{ompd\_get\_ancestor\_task\_region}}{get-ancestor-task-region:def}
-to find the task's parent region, and then call \verb|ompd_get_task_frame|
-for the parent task.
+It can then use \refdef{\texttt{ompd\_get\_scheduling\_ancestor\_task\_region}}{get-scheduling-ancestor-task-region:def} to find the next task in the
+thread's stack, and then call \verb|ompd_get_task_frame| for the parent task.
 %
-The frames between the parent task's reenter address and the top
+The frames between the scheduling parent task's reenter address and the top
 task's exit address are frames in which the thread is executing OpenMP
 runtime code.
 \begin{notes}
@@ -298,6 +296,11 @@ \subsection{Stack Unwinding}
 This process can be repeated to allow all frames in the thread's
 backtrace that correspond to execution in the OpenMP runtime to be
 identified.
-%
+
+Using the generating ancestor operation \refdef{\texttt{ompd\_get\_generating\_ancestor\_task\_region}}{get-generating-ancestor-task-region:def},
+the same process can be used to determine the chain logical ancestors.
+Note that in this case the logical backtrace may traverse
+across the stacks of different threads.
+
 The position within the stack frame where the runtime addresses point
-is implementation defined.
+is implementation defined.

sec_handle_mgmt.tex

@@ -1 +1 @@
-2.000
+2.001