diff options
Diffstat (limited to 'doc/documentation.tex')
-rw-r--r-- | doc/documentation.tex | 39 |
1 files changed, 32 insertions, 7 deletions
diff --git a/doc/documentation.tex b/doc/documentation.tex index d6adc5d..2fb7e76 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -83,7 +83,7 @@ int SpaceMask\_RegisterType(const char* \emph{type\_name}, \begin{description} \item[\emph{type\_name}] The name of the new type to be registered; \item[\emph{nstates}] The number of states in the new type; - \item[\emph{state\_list}] A list of names, one for each state. + \item[\emph{state\_list}] A list of names, one for each state, or NULL. \end{description} } } @@ -96,6 +96,13 @@ function returns a $-1$ if the required states cannot be allocated (for example, if there are not enough free bits remaining in the mask), otherwise it returns $0$. +It is possible to allocate a portion of the mask without assigning +names to any of the states by passing NULL as the \emph{state\_list}. +This is useful when some integer number of states is required for a +given type, but the number of states and appropriate names are not +known at compile time. States which are allocated in this way can be +accessed using the \texttt{SpaceMask\_GetStateBitsList()}. + New states can be added to an already allocated type using the function: @@ -199,12 +206,31 @@ bitmask corresponding to the given type or state. For example, if a given type uses three bits of the mask, the returned value could be the integer corresponding to the bitfield $001110000$\ldots, where the location of $1$s indicates the bits which have been allocated to the -given type. A return value of $-1$ indicates that the bitmask could +given type. A return value of $0$ indicates that the bitmask could not be determined for some reason (for example, the requested state -was not previously registered)\footnote{Note that a potential -ambiguity arises here, in that if the full mask is allocated to a -single type, then $-1$ is a valid state. It is assumed that this -eventuality won't arise in practice.}. +was not previously registered). + +All of the state masks allocated for a given type can be retrieved +using the following function: + +\indent\parbox{\linewidth}{ +\vspace{\baselineskip}\noindent\texttt{ +CCTK\_INT* SpaceMask\_GetStateBitsList(const char* \emph{type\_name}) +}\\ +\hspace*{10mm}\parbox{\linewidth}{ +\begin{description} + \item[\emph{type\_name}] The type for which the bitmask is to be + determined. +\end{description} +}} + +The return value is a list of integers, with a length corresponding to +the number of states of the given type. Each of the entries is a +bitmask which identifies the state. List entries are returned in the +order in which they were originally assigned. This allows for a simple +correspondence between states and integers (given by the index of the +list entry). \emph{A fortran wrapper does not currently exist for this +functionality.} The following macros have been defined for fast setting and checking of the mask by direct bitwise operations: @@ -385,7 +411,6 @@ of the mask required grid symmetries to work for integer grid functions. This was done by Thomas Radke. Peter Diener helped with the coding of the Fortran90 bitwise operators. -\pagebreak \section{Appendix} \subsection{Example: C code}\label{app:eg_C} |