Update the function aliasing documentation.

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

3 files changed, 90 insertions, 54 deletions

diff --git a/doc/ReferenceManual/CCTKReference.tex b/doc/ReferenceManual/CCTKReference.tex
index 745dc26e..f3119e43 100644
--- a/doc/ReferenceManual/CCTKReference.tex
+++ b/doc/ReferenceManual/CCTKReference.tex
@@ -381,6 +381,10 @@ from Fortran.
 %notyet   Registers a routine as a \code{CCTK\_InterpLocalWarped}
 %notyet   interpolation operator
 
+\item[\code{CCTK\_IsFunctionAliased}]
+  [\pageref{CCTK-IsFunctionAliased}]
+  Reports whether an aliased function has been provided
+
 \item[\code{CCTK\_IsImplementationActive}]
   [\pageref{CCTK-IsImplementationActive}]
   Reports whether an implementation was activated in a parameter file
@@ -4001,13 +4005,13 @@ A negative return code indicates an error condition:
 %notyet \end{SeeAlsoSection}
 %notyet
 %notyet \begin{ErrorSection}
-%notyet	\begin{Error}{}
-%notyet	To find the numerical
-%notyet	values of the error codes (or more commonly, to find which error code
-%notyet	corresponds to a given numerical value), look in the files
-%notyet	\code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
+%notyet \begin{Error}{}
+%notyet To find the numerical
+%notyet values of the error codes (or more commonly, to find which error code
+%notyet corresponds to a given numerical value), look in the files
+%notyet \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
 in the \code{src/include/} directory in the Cactus flesh.
-%notyet	\end{Error}
+%notyet \end{Error}
 %notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE}
 %notyet one or more of the interpolation points is out of range
 %notyet (in this case additional information about the out-of-range point
@@ -4633,13 +4637,13 @@ if (CCTK_InterpLocalUniform(N_DIMS,
 %notyet \end{SeeAlsoSection}
 %notyet
 %notyet \begin{ErrorSection}
-%notyet	\begin{Error}{}
-%notyet	To find the numerical
-%notyet	values of the error codes (or more commonly, to find which error code
-%notyet	corresponds to a given numerical value), look in the files
-%notyet	\code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
+%notyet \begin{Error}{}
+%notyet To find the numerical
+%notyet values of the error codes (or more commonly, to find which error code
+%notyet corresponds to a given numerical value), look in the files
+%notyet \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
 in the \code{src/include/} directory in the Cactus flesh.
-%notyet	\end{Error}
+%notyet \end{Error}
 %notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE}
 %notyet one or more of the interpolation points is out of range
 %notyet (in this case additional information about the out-of-range point
@@ -4942,6 +4946,23 @@ CCTK_InterpRegisterOpLocalUniform(AEILocalInterp_InterpLocalUniform,
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % CCTK\_InterpRegisterOpLocalWarped here
 
+% lib/sbin/CreateFunctionBindings.pl
+\begin{CCTKFunc}{CCTK\_IsFunctionAliased}{Reports whether an aliased function has been provided}
+\label{CCTK-IsFunctionAliased}
+\function{int}{integer}{istat}
+\argument{const char *}{character*(*)}{functionname}
+\showargs
+\begin{params}
+\parameter{istat}{the return status}
+\parameter{functionname}{the name of the function to check}
+\end{params}
+\begin{discussion}
+This function returns a non-zero value if the function given by
+\code{functionname} is provided by any active thorn, and zero
+otherwise.
+\end{discussion}
+\end{CCTKFunc}
+
 % ActiveThorns.c
 \begin{CCTKFunc}{CCTK\_IsImplementationActive}{Reports whether an implementation was activated in a parameter file}
 \label{CCTK-IsImplementationActive}
diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index bc159f1a..15499728 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -287,24 +287,26 @@ Both default to \verb|HEADER|.
 If any aliased function is to be used or provided by the thorn then
 the prototype must be declared with the form:
 \begin{verbatim}
-<return_type> FUNCTION <alias>(<arg1_type> <arg1>, ...)
+<return_type> FUNCTION <alias>(<arg1_type> <intent1> [ARRAY] <arg1>, ...)
 \end{verbatim}
 The \verb|<return_type>| must be either \verb|void|, \verb|CCTK_INT|
-or \verb|CCTK_REAL|. The name of the aliased function \verb|<alias>|
-must be 21 characters or less, contain at least one uppercase and one
-lowercase letter, and follow the C standard for function names.  The
-type of each argument, \verb|<arg*_type>| must be a \verb|CCTK| type
-in \verb|INT,REAL,STRING,POINTER,INT:ARRAY,REAL:ARRAY|. Arguments may
-only be modified if they have the \verb|ARRAY| suffix.
+or \verb|CCTK_REAL|. The keyword \verb|SUBROUTINE| is equivalent to
+\verb|void FUNCTION|. The name of the aliased function \verb|<alias>|
+must contain at least one uppercase and one lowercase letter and
+follow the C standard for function names.  The type of each argument,
+\verb|<arg*_type>| must be a \verb|CCTK| type in
+\verb|INT,REAL,STRING,POINTER|. The intent of each argument,
+\verb|<intent*>| must be either \verb|IN| or \verb|OUT|. An argument
+should only be modified if it is declared to have intent
+\verb|OUT|. If the argument is an array then the prefix \verb|ARRAY|
+should also be given.
 
 If the argument \verb|<arg*>| is a function pointer then the argument
 itself (which will preceded by the return type) should be
 \begin{verbatim}
-CCTK_FPOINTER <function_arg1>(<arg1_type> <arg1>, ...)
+CCTK_FPOINTER <function_arg1>(<arg1_type> <intent1> <arg1>, ...)
 \end{verbatim}
-Function pointers may not be nested. The combined character length of
-\verb|<alias>| and \verb|<function_arg*>| must be 21 characters or
-less. 
+Function pointers may not be nested. 
 
 If an aliased function is to be used then the block
 \begin{verbatim}
@@ -316,11 +318,10 @@ If a function is provided then the block
 \begin{verbatim}
 PROVIDES FUNCTION <alias> WITH <provider> LANGUAGE <providing_language>
 \end{verbatim}
-is required. As with the alias name, \verb|<provider>| must be 21
-characters or less, contain at least one uppercase and one lowercase
-letter, and follow the C standard for function names. Currently the
-only supported values of \verb|<providing_language>| are \verb|C| and
-\verb|Fortran|.
+is required. As with the alias name, \verb|<provider>| must contain at
+least one uppercase and one lowercase letter and follow the C standard
+for function names. Currently the only supported values of
+\verb|<providing_language>| are \verb|C| and \verb|Fortran|.
 
 
 \subsection{Variable blocks}
@@ -706,11 +707,11 @@ through them.
 \begin{Lentry}
 
 \item[{\tt CCTK\_STARTUP}] 
-	Run before any grids are constructed, this is 
-	the timebin for example where grid independent information 
- 	(e.g.\ output methods, reduction operators) is registered. 
-	Note that since no grids are setup at this point, grid 
-	variables cannot be used in routines scheduled here.
+        Run before any grids are constructed, this is 
+        the timebin for example where grid independent information 
+        (e.g.\ output methods, reduction operators) is registered. 
+        Note that since no grids are setup at this point, grid 
+        variables cannot be used in routines scheduled here.
 
 \item[{\tt CCTK\_RECOVER\_PARAMETERS}]
         Used by thorns with relevent IO methods as the point 
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 5ca1d7b8..2829d2dd 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -1021,7 +1021,7 @@ Fundamental information about grid functions (e.g.\ local grid size and location
 \item {\tt CCTK\_Groupbbox[GN|GI|VN|VI]}      An array of  integers 
       which indicate whether the boundaries are internal boundaries
       (e.g.\ between processors), or physical boundaries. 
-	A value of 1 indicates
+        A value of 1 indicates
       a physical (outer) boundary at the edge of the computational grid,
       and 0 indicates an internal boundary.  
 
@@ -3784,7 +3784,7 @@ To use an aliased function you must first declare it in your {\tt
 interface.ccl} file. Declare the prototype as, for example,
 
 {\tt
-CCTK\_REAL FUNCTION SumStuff(CCTK\_REAL x, CCTK\_REAL y)
+CCTK\_REAL FUNCTION SumStuff(CCTK\_REAL IN x, CCTK\_REAL IN y)
 }
 
 \noindent and that this function will be used in your thorn by
@@ -3797,7 +3797,12 @@ A prototype of this function will be available to any C routine that
 includes the {\tt cctk.h} header file. However, in a Fortran file that
 uses the {\tt implicit none} declaration the function will have to be
 explicitly declared; a definition will not be included in the {\tt
-DECLARE\_CCTK\_FUNCTIONS} macro.
+  DECLARE\_CCTK\_FUNCTIONS} macro. The keywords {\tt IN} and {\tt OUT}
+work in the same fashion as {\tt INTENT} statements in Fortran 90.
+That is, the C prototype will expect an argument with intent {\tt IN}
+to be a value and one with intent {\tt OUT} to be a pointer. There
+also exists the {\tt ARRAY} keyword for passing arrays of any
+dimension.
 
 
 \subsection{Providing a function}
@@ -3807,7 +3812,7 @@ your {\tt interface.ccl} file. A statement containing the name of the
 providing function and the language it is provided in must also be
 given. For example,
 \begin{verbatim}
-CCTK_REAL FUNCTION SumStuff(CCTK_REAL x, CCTK_REAL y) 
+CCTK_REAL FUNCTION SumStuff(CCTK_REAL IN x, CCTK_REAL IN y) 
 PROVIDES FUNCTION SumStuff WITH AddItUp LANGUAGE C
 \end{verbatim}
 The appropriate function must then be provided somewhere in this
@@ -3827,29 +3832,27 @@ work. These are
     CCTK\_REAL}. Standard types such as {\tt int} are not allowed.
 \item The type of an argument must be one of scalar types {\tt
     CCTK\_INT, CCTK\_REAL, CCTK\_STRING, CCTK\_POINTER,
-    CCTK\_FPOINTER}, or an array or pointer type {\tt CCTK\_INT:ARRAY,
-    CCTK\_REAL:ARRAY}. The scalar types are assumed to be not
+    CCTK\_FPOINTER}, or an array or pointer type {\tt CCTK\_INT ARRAY,
+    CCTK\_REAL ARRAY}. The scalar types are assumed to be not
   modifiable. Any changes made to a scalar argument by a providing
   function may be silently lost, or may not; it is dependent on the
   language of the providing and calling function. If you wish to
-  modify an argument then it must have the {\tt ARRAY} suffix (and
-  hence must be either a {\tt CCTK\_INT} or {\tt CCTK\_REAL}).
+  modify an argument then it must have intent {\tt OUT} (and hence
+  must be either a {\tt CCTK\_INT} or {\tt CCTK\_REAL}).
 \item The name of both the aliased and providing function are
   restricted. They must follow the standard C semantics (start with a
   letter, contain only letters, numbers or underscores). Additionally,
   they must be mixed case (that is, contain at least one uppercase and
-  one lowercase letter) and be less than 21 characters long. The names
-  of the aliased and providing functions must be distinct.
+  one lowercase letter). The names of the aliased and providing
+  functions must be distinct.
 \item If an argument is a function pointer then the syntax looks like 
 \begin{verbatim}
-CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER  func(CCTK_REAL x), \
-                    CCTK_REAL xmin, CCTK_REAL xmax)
+CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER  func(CCTK_REAL IN x), \
+                    CCTK_REAL IN xmin, CCTK_REAL IN xmax)
 \end{verbatim}
-  It is assumed that the function pointer argument has the
-  same language as the calling function. The name of the function
-  pointer argument should be short, as the total length of the providing
-  function name and the function pointer argument must be less than 21
-  characters.  Function pointer arguments may not be nested.
+  It is assumed that the function pointer argument has the same
+  language as the calling function. Function pointer arguments may not
+  be nested.
 \item {\tt CCTK\_STRING} arguments follow the same conventions as in
   the previous section. That is, they must appear at the end of the
   argument list, there must be at most three, and a function with a
@@ -3864,7 +3867,7 @@ CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER  func(CCTK_REAL x), \
 \item A C function is provided that adds together two real numbers. The {\tt
     interface.ccl} should read
 \begin{verbatim}
-    CCTK_REAL FUNCTION SumStuff(CCTK_REAL x, CCTK_REAL y)
+    CCTK_REAL FUNCTION SumStuff(CCTK_REAL IN x, CCTK_REAL IN y)
     PROVIDES FUNCTION SumStuff WITH AddItUp LANGUAGE C 
     USES FUNCTION SumStuff
 \end{verbatim}
@@ -3872,22 +3875,33 @@ CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER  func(CCTK_REAL x), \
 \item A Fortran function is provided that inverts a real number. The {\tt
     interface.ccl} should read
 \begin{verbatim}
-    void FUNCTION Invert(CCTK_REAL:ARRAY x)
+    SUBROUTINE Invert(CCTK_REAL OUT x)
     PROVIDES FUNCTION Invert WITH FindInverse LANGUAGE Fortran 
     USES FUNCTION Invert
 \end{verbatim}
+\noindent Note that {\tt SUBROUTINE} has the same meaning as {\tt void
+  FUNCTION}. 
 
 \item A Fortran function is provided that integrates any function over
   an interval. The {\tt interface.ccl} should read
 \begin{verbatim}
-    CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER  func(CCTK_REAL x), \ 
-                        CCTK_REAL xmin, CCTK_REAL xmax)
+    CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER  func(CCTK_REAL IN x), \ 
+                        CCTK_REAL IN xmin, CCTK_REAL IN xmax)
     PROVIDES FUNCTION Integrate WITH SimpsonsRule LANGUAGE Fortran 
     USES FUNCTION Integrate
 \end{verbatim}
 
 \end{itemize}
 
+\subsection{Testing aliased functions}
+
+The calling thorn does not know if an aliased function is even
+provided by another thorn. Calling an aliased function that has not
+been provided will lead to a level 0 warning message, stopping the
+code. In order to check if a function has been provided by some thorn,
+use the {\tt CCTK\_IsFunctionAliased} function described in the
+function reference section.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Naming conventions}