documentation for function aliasing

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

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 212739d9..0d0f1539 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -3689,6 +3689,137 @@ strings from C.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\section{Function aliasing}
+
+As well as calling functions in a different language, Cactus offers a
+mechanism for calling a function in a different thorn where you need
+not know which thorn is actually providing the function, nor what
+language the function is provided in. The idea of {\it function
+aliasing} is similar to that of thorns; the routine that calls a
+function should not need to know anything about it except that the
+function exists.
+
+Function aliasing is quite restrictive because of the problems
+involved in inter-language calling, as seen in the previous
+section. Function aliasing is also comparatively inefficient and
+should not be used in a part of your code where efficiency is
+important. 
+
+Function aliasing is language neutral. However, the syntax is strongly
+based on C.
+
+\subsection{Using an aliased function}
+
+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)
+}
+
+\noindent and that this function will be used in your thorn by
+
+{\tt
+USES FUNCTION SumStuff
+}
+
+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.
+
+
+\subsection{Providing a function}
+
+To provide an aliased function you must again add the prototype to
+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) 
+PROVIDES FUNCTION SumStuff WITH AddItUp LANGUAGE C
+\end{verbatim}
+The appropriate function must then be provided somewhere in this
+thorn.
+
+It is necessary to specify the language of the providing function; no
+default will be assumed. 
+
+
+\subsection{Conventions and restrictions}
+
+Various restrictions are necessary to make function aliasing
+work. These are
+\begin{itemize}
+\item The return type of any function must be either {\tt void} or one
+  of the Cactus data types {\tt CCTK\_INT} or {\tt
+    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
+  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}).
+\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.
+\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)
+\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.
+\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
+  {\tt CCTK\_STRING} argument can only be provided in C, not Fortran,
+  although they may be called from either.
+\end{itemize}
+
+
+\subsection{Examples}
+
+\begin{itemize}
+\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)
+    PROVIDES FUNCTION SumStuff WITH AddItUp LANGUAGE C 
+    USES FUNCTION SumStuff
+\end{verbatim}
+
+\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)
+    PROVIDES FUNCTION Invert WITH FindInverse LANGUAGE Fortran 
+    USES FUNCTION Invert
+\end{verbatim}
+
+\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)
+    PROVIDES FUNCTION Integrate WITH SimpsonsRule LANGUAGE Fortran 
+    USES FUNCTION Integrate
+\end{verbatim}
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \section{Naming conventions}
 
 \begin{itemize}