From 22b8b80801ec209e4e3006e6be2de62e1f90a7ce Mon Sep 17 00:00:00 2001 From: pollney Date: Mon, 26 May 2003 07:28:49 +0000 Subject: Added SpaceMask_GetMaskBitsList() function, which returns an ordered list of all the bitmasks associated with each state of a given type. Also allowed for passing a NULL as the list of state names on registry, in which case the mask states are allocated but not named. These additions make it easier to allocate a mask bitfield of a size that might only be known at runtime. More routines for working with mask states as integers might be useful in the future. git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/SpaceMask/trunk@31 a491c6a4-70bf-4b89-8b36-d6c0cb1f094e --- doc/documentation.tex | 39 ++++++++++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 7 deletions(-) (limited to 'doc') 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} -- cgit v1.2.3