remove all mention of the auto-destroy flag

(we've decided it was a mistake, and I'll shortly remove it from the code)


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

1 files changed, 26 insertions, 36 deletions

diff --git a/doc/UsersGuide/UtilityRoutines.tex b/doc/UsersGuide/UtilityRoutines.tex
index d4792137..e23e595c 100644
--- a/doc/UsersGuide/UtilityRoutines.tex
+++ b/doc/UsersGuide/UtilityRoutines.tex
@@ -247,13 +247,17 @@ error if the string is too long for the buffer.
 \section{Table Options}
 
 A table has an integer ``flags word'' which may be used to specify
-various options, via bit flags defined in \verb|"util_Table.h"|:
+various options, via bit flags defined in \verb|"util_Table.h"|.
+At present there is only a single option:
 \begin{description}
-\item[Keys May be Case-Sensitive or Case-Insensitive]
-	By default keys are compared as C-style character strings,
-	compared with the standard \verb|strcmp()| function.
-	However, optionally keys may be made case-insensitive,
-	compared with \verb|Util_StrCmpi()|.%%%
+\item[Keys May be Case-Sensitive or Case-Insensitive:]
+	By default keys are treated as C-style character strings,
+	and the table functions compare them with the standard C
+	\verb|strcmp()| function.
+	However, by setting the \verb|UTIL_TABLE_FLAGS_CASE_INSENSITIVE|
+	bit in the flags word, this table's keys may be made
+	case-insensitive, \ie{} the table routines then compare
+	this table's keys with \verb|Util_StrCmpi()|.%%%
 \footnote{%%%
  	 It's not entirely clear how non-ASCII characters
 	 like \c{c}, \'{e}, \ss, \dots should be handled in
@@ -263,26 +267,6 @@ various options, via bit flags defined in \verb|"util_Table.h"|:
 	 In general, Cactus basically just ignores
 	 internationalization issues.  Sigh\dots
 	 }%%%
-\item[Auto-Destruction of Tables]
-	By default, you (the programmer) are responsibe for
-	destroying a table when you're done with it.  However,
-	tables also support an ``auto-destroy'' flag.  If this
-	is set for a table, then the table will automagically
-	be destroyed when the {\em next\/} table is created
-	(regardless of what flags that table has).
-	Thus at most one table with the auto-destroy flag set
-	can exist at any time, and, in practice, so long as
-	you don't store huge arrays in them, there's no need
-	to bother with explicitly destroying such tables
-	(\ie{} the memory waste is pretty small).
-	The convenience routine
-	\verb|Util_TableCreateFromString()| sets the
-	auto-destroy flag for the tables it creates, so if
-	you're willing to skip error checking, you can use
-	it directly in another function call, as in (for example)
-\begin{verbatim}
-CCTK_SomeCactusFunction(..., Util_TableCreateFromString("answer=42"), ...);
-\end{verbatim}
 \end{description}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -332,26 +316,32 @@ using an iterator to print out all the entries in a table.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{Multithreading}
+\section{Multithreading and Multiprocessor Issues}
 
 {\bf At the moment, the table functions are {\em not\/} thread-safe
 in a multithreaded environment!}  However, this should change in
 the not-too-distant future: then all the table functions will default
 to being thread-safe.  That is, user code will be able call these
-functions concurrently from multiple threads, with the thread routines
-taking care of any necessary locking.  (There may be a flags-word bit
-to suppress this for maximum performance if you know you won't be
-making concurrent calls from multiple threads.)
+functions concurrently from multiple threads, with the table functions
+automatically doing any necessary locking.%%%
+\footnote{%%%
+	 For the implementation, this means that we will need a
+	 reader/writer lock for each table and for each iterator:
+	 any number of threads will be able to concurrently read
+	 the data structure, but any write will require exclusive
+	 access.
+	 }%%%
+{}  (We may add a flags-word bit to suppress this for maximum
+performance if you know you won't be making concurrent calls from
+multiple threads.)
 
 Note that tables and iterators will still be process-wide, i.e. all
 threads see the same tables and iterators (think of them as like the
 Unix current working directory, with the various routines which modify
-the table or change iterators acting like a Unix \verb|chdir()| system call).
+the table or change iterators acting like a Unix \verb|chdir()| system
+call).
 
-For the implementation, this means that we will need a reader/writer
-lock for each table and for each iterator: any number of threads will
-be able to concurrently read the data structure, but any write will
-require exclusive access.
+In a multiprocessor environment, tables are always processor-local.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%