add function to query name of currently scheduled function

this adds a function CCTK_ScheduleQueryCurrentFunction which returns the
cFunctionData of the function currently executing via
CCTK_CallScheduledFunction



git-svn-id: http://svn.cactuscode.org/flesh/trunk@4805 17b73243-c579-4c4c-a9d2-2d5706c11dac

2 files changed, 63 insertions, 0 deletions

diff --git a/doc/ReferenceManual.pdf b/doc/ReferenceManual.pdf
index 29696f29..a90197c4 100644
--- a/doc/ReferenceManual.pdf
+++ b/doc/ReferenceManual.pdf
diff --git a/doc/ReferenceManual/CCTKReference.tex b/doc/ReferenceManual/CCTKReference.tex
index d268dc78..1908547b 100644
--- a/doc/ReferenceManual/CCTKReference.tex
+++ b/doc/ReferenceManual/CCTKReference.tex
@@ -11095,6 +11095,69 @@ if (CCTK_MyProc(cctkGH)==3)
 
 
 
+% ScheduleInterface.c
+\begin{FunctionDescription}{CCTK\_ScheduleQueryCurrentFunction}
+  \label{CCTK-ScheduleQueryCurrentFunction}
+   Return the cFunctionData of the function currently executing via
+   \texttt{CCTK\_CallFunction}.
+  
+  \begin{SynopsisSection}
+    \begin{Synopsis}{C}
+\begin{verbatim}
+#include "cctk.h"
+const cFunctionData *CCTK_ScheduleQueryCurrentFunction(const cGH *GH)
+\end{verbatim}
+    \end{Synopsis}
+  \end{SynopsisSection}
+  
+  \begin{ResultSection}
+    \begin{ResultNote}
+      Data of last call to \texttt{CCTK\_CallFunction}, or
+    \end{ResultNote}
+    \begin{Result}{NULL}
+      if not within a scheduled function.
+    \end{Result}
+  \end{ResultSection}
+  
+  \begin{ParameterSection}
+    \begin{Parameter}{cctkGH}
+      Pointer to a Cactus grid hierarchy.
+    \end{Parameter}
+  \end{ParameterSection}
+  
+  \begin{Discussion}
+    Returns a data structure containing the thorn and routine name of the
+    currently executing function as well as the Cactus bin name. If no
+    function is currently executing, returns \code{NULL}. This is intended to
+    be used by thorns providing callable functions to identify their caller
+    when reporting errors.
+  \end{Discussion}
+  
+  \begin{SeeAlsoSection}
+    \begin{SeeAlso}{CCTK\_CallFunction}
+      Calls a function depending upon the data passed in the the fdata
+      structure.
+    \end{SeeAlso}
+  \end{SeeAlsoSection}
+
+  \begin{ExampleSection}
+    \begin{Example}{C}
+      Output the name of the currently scheduled function:
+\begin{verbatim}
+#include <stdio.h>
+#include "cctk.h"
+const cFunctionData *fdata = CCTK_QueryScheduledFunction(cctkGH);
+printf("scheduled function: %s::%s AT %s\n",
+       fdata->thorn, fdata->routine, fdata->where);
+\end{verbatim}
+\end{Example}
+  \end{ExampleSection}
+  
+\end{FunctionDescription}
+
+
+
+
 % CommOverloadables.c
 \begin{FunctionDescription}{CCTK\_SetupGH}{Setup a new GH}
 \label{CCTK-SetupGH}