diff options
author | goodale <goodale@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 1999-09-27 15:32:55 +0000 |
---|---|---|
committer | goodale <goodale@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 1999-09-27 15:32:55 +0000 |
commit | e097705303bdcd425139b37e825297b74015f63e (patch) | |
tree | 39c76d0dc3a64b90985b6664edd0410951767bba | |
parent | e67da5739cb0ce1a17f1c469afb4b020da013184 (diff) |
Fleshed this out a bit.
Tom
git-svn-id: http://svn.cactuscode.org/flesh/trunk@999 17b73243-c579-4c4c-a9d2-2d5706c11dac
-rw-r--r-- | doc/UsersGuide/Infrastructure.tex | 247 |
1 files changed, 233 insertions, 14 deletions
diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex index 44bc0aa6..3d54aeda 100644 --- a/doc/UsersGuide/Infrastructure.tex +++ b/doc/UsersGuide/Infrastructure.tex @@ -15,10 +15,67 @@ \item{} Overloadable functions \end{itemize} +\chapter{Concepts and Terminology} +\label{chap:cote} - \section{Overloadable functions} +\section{Overloading and Registration} + +The flesh defines a core API which guarantees the presence of a set of +functions. Although the flesh guarantees the presence of these functions, +they can be provided by thorns. Thorns do this either by the {\em overloading} +or the {\em registration} of functions. + +\subsection{Overloading} + +Some functions can only be provided by one thorn. The first thorn to +{\em overload} this function succeeds, and any later attempt to overload +the function fails. For each overloadable function there is a function +with a name something like {\tt CCTK\_Overload...} which is passed the +function pointer. + +\subsection{Registration} + +Some functions may be provided by several thorns. The thorns {\em register} +their function with the flesh, and when the flesh-provided function is called, +the flesh calls all the registered functions. + +\section{GH Extensions} + +A GH extension is a way to associate data with each cGH. This data should be data +that is required to be associated with a particular GH by a thorn. + +Each GH extension is given a unique handle. + +\section{IO Methods} + +An IO method is a distinct way to output data. Each IO method has a unique name, +and the flesh-provided IO functions operate on all registered IO methods. + +\chapter{GH Extensions} + +A GH extension is created by calling {\tt CCTK\_RegisterGHExtension} , with the +name of the extension. This returns a unique handle that identifies the extension. +(This handle can be retrieved at any time by a call to {\tt CCTK\_GHExtensionHandle}.) + +Associated with a GH extension are three functions + +\begin{itemize} +\item[SetupGH] +this is used to actually create the data structure holding the extension. It +is called when a new cGH is created. +\item[InitGH] +this is used to initialise the extension. It is called after the scheduler has +been initialised on the cGH. +\item[rfrTraverse] +this is called whenever the schedule tree is due to be traversed on the GH. It +should initialise the data on the cGH and the call {\tt rfrTraverse} to traverse +the schedule tree. +\end{itemize} + +\chapter{IO Methods} + +\chapter{Overloadable and Registerable Functions in Main} - \subsection{Core functions} \begin{tabular}{|l|l|} \hline {\bf Function} & {\bf Default} \\ \hline {\t CCTK\_Initialise} &\\ @@ -27,15 +84,8 @@ \hline \end{tabular} - \subsection{IO Functions} - \begin{tabular}{|l|l|} - \hline {\bf Function} & {\bf Default} \\ - \hline {\t CCTK\_OutputGH} & \\ - \hline {\t CCTK\_OutputVarAsByMethod} & \\ - \hline - \end{tabular} +\chapter{Overloadable and Registerable Functions in Comm} - \subsection{Driver functions} \begin{tabular}{|l|l|} \hline {\bf Function} & {\bf Default} \\ \hline {\t CCTK\_SyncGroup} &\\ @@ -47,13 +97,182 @@ \hline {\t CCTK\_Reduce} &\\ \hline {\t CCTK\_Interp} &\\ \hline {\t CCTK\_ParallelInit} &\\ - \hline {\t CCTK\_Init} &\\ - \hline {\t CCTK\_Exit} &\\ - \hline {\t CCTK\_Abort} &\\ - \hline {\t CCTK\_SetupGH} &\\ \hline \end{tabular} +\chapter{Overloadable and Registerable Functions in IO} + + \begin{tabular}{|l|l|} + \hline {\bf Function} & {\bf Default} \\ + \hline {\t CCTK\_OutputGH} & \\ + \hline {\t CCTK\_OutputVarAsByMethod} & \\ + \hline + \end{tabular} + +\chapter{Adding a Driver} + +The flesh knows nothing about memory allocation for grid variables, or about how +to communicate data when synchronisation is called for. It knows nothing about +multiple patches or adaptive mesh refinement. All this is the job of a driver. + +\section{Anatomy} + +A driver consists of a Startup routine which creates a GH extension and +registers its associated functions, and overloads the communication functions. +It may optionally register interpolation, reduction, and IO methods. + +A driver may also overload the default Initialisation and Evolution routines, +although a simple unigrid evolver is supplied in the flesh. + +\section{Startup} + +A driver consists of a GH extension, and the following overloaded +functions. + +\begin{enumerate} +\item{} CCTK\_EnableGroupStorage +\item{} CCTK\_DisableGroupStorage +\item{} CCTK\_ArrayGroupSizeB +\item{} CCTK\_QueryGroupStorageB +\item{} CCTK\_SyncGroup +\item{} CCTK\_EnableGroupComm +\item{} CCTK\_DisableGroupComm +\item{} CCTK\_Barrier +\item{} CCTK\_OverloadParallelInit +\item{} CCTK\_OverloadExit +\item{} CCTK\_OverloadAbort +\item{} CCTK\_OverloadMyProc +\item{} CCTK\_OverloadnProcs +\end{enumerate} + +\section{The GH Extension} + +The GH extension is where the driver stores all its grid-dependent information. +This is stuff like any data associated with a grid variable (e.g. storage and +communication state), how many grids if it is AMR, ... It is very difficult to +describe in general, but one simple example might be + +\begin{verbatim} + +struct SimpleExtension +{ + /* The data assocatiated with each variable */ + /* data[var][timelevel][ijk] + void ***data +} ; + +\end{verbatim} + +with a SetupGH routine like. + +\begin{verbatim} + +struct SimpleExtension *SimpleSetupGH(t_Fleshconfig *config, int conv_level, cGH *GH) +{ + struct SimpleExtension *extension; + + extension = NULL; + + if(conv_level < max_conv_level) + { + /* Create the extension */ + extension = malloc(sizeof(struct SimpleExtension)); + + /* Allocate data for all the variables */ + extension->data = malloc(num_vars*sizeof(void**)); + + for(var = 0 ; var < num_vars; var++) + { + /* Allocate the memory for the time levels */ + extension->data[var] = malloc(num_var_time_levels*sizeof(void *)); + + for(time_level = 0; time_level < num_var_time_level; time_level++) + { + /* Initialise the data to NULL */ + extension->data[var][time_level] = NULL; + } + } + } + + return extension; +} + +\end{verbatim} + +Basically all this example is doing is preparing a data array for use. The +function can query the flesh for information on every variable. Note that +scalars should always have memory actually assigned to them. + +An {\tt InitGH} function isn't strictly necessary, and in ths case it could just +be a dummy function. + +The {\tt rfrTravers} function needs to fill out the cGH data and then call +{\tt CCTK\_Schedule} to have the functions scheduled at that point executed on the +grid. + +\section{Memory Functions} + +These consist of +\begin{enumerate} +\item{} CCTK\_EnableGroupStorage +\item{} CCTK\_DisableGroupStorage +\item{} CCTK\_QueryGroupStorageB +\item{} CCTK\_ArrayGroupSizeB +\end{enumerate} + +\subsection{En/Disable Group Storage} + +These are responsible for switching the memory for all variables +in a group on or off. They should return the former state, e.g. +if the group already has storage assigned, they should return 1. + +In our simple example above, the enabling routine would look +something like + +\begin{verbatim} + +int SimpleEnableGroupStorage(cGH *GH, const char *groupname) +{ + + extension = (struct SimpleExtension *)GH->extensions[SimpleExtension]; + + if(extension->data[first][0][0] == NULL) + { + for(var = first; var <= last; var++) + { + allocate memory for all time levels; + } + retcode = 0; + } + else + { + retcode = 1; + } + + return retcode; +} + +\end{verbatim} + +Note that scalars should always have memory assigned. + +The disable function is basically the reverse of the enable one. + +The QueryGroupStorage function basically returns true or false if there is storage +for the group, and the ArrayGroupSize returns the size of the grid function or array +group in a particular direction. + +\subsection{En/Disable Group Comm} + +These are the communication analogues to the storage functions. Basically they flag +that communication is to be done on that group or not, and may initialise data +structures for the communication. + + + +\chapter{Adding an IO layer} + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{cactuspart} |