[Xsb-commits] CVS: XSB/docs/userman exceptions.tex,1.5,1.6 rbltin.tex,1.40,1.41 system.tex,1.52,1.53

[Terrance S. <ts...@us...>]

Update of /cvsroot/xsb/XSB/docs/userman
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17826

Modified Files:
	exceptions.tex rbltin.tex system.tex 
Log Message:
Added check_one_thread/3 to error_handler.

Added this check, and various others to predicates in consult.P
to ensure thread safety, and to throw errors when called
improperly.

Documented these changes in the manual.



Index: exceptions.tex
===================================================================
RCS file: /cvsroot/xsb/XSB/docs/userman/exceptions.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- exceptions.tex	26 Dec 2005 17:14:43 -0000	1.5
+++ exceptions.tex	24 Jan 2006 23:37:55 -0000	1.6
@@ -484,6 +484,18 @@
 if not it throws an instantiation error~\footnote{The representation
 of streams in XSB is subject to change.}.
 
+\ournewitem{check\_one\_thread(+Operation,+Object\_Type,+Predicate)}{error\_handler}
+\index{\texttt{check\_one\_thread/3}} 
+%
+In the Multi-Threaded Engine, checks that there is only one active
+thread: if not, a miscellaneous error is thrown indicating that {\tt
+  Operation} is not permitted on {\tt ObjectType} as called by {\tt
+  Predicate}, when more than one thread is active.  This check
+provides a convenient way to allow inclusion of certain operations
+that are difficult to make thread-safe by other means.
+
+In the single-threaded engine this predicate always succeeds.
+
 \end{description}
 
 %----------------------------------------------------------------------------

Index: rbltin.tex
===================================================================
RCS file: /cvsroot/xsb/XSB/docs/userman/rbltin.tex,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- rbltin.tex	26 Dec 2005 17:14:43 -0000	1.40
+++ rbltin.tex	24 Jan 2006 23:37:55 -0000	1.41
@@ -490,10 +490,19 @@
 
 {\bf Error Cases}
 \bi
+\item 	{\tt FileName} is a variable
+ \bi
+ \item 	{\tt instantiation\_error}
+ \ei
 \item 	{\tt FileName} is not an atom.
-\bi
-\item 	{\tt type\_error(FileName,atom)}
-\ei
+ \bi
+ \item 	{\tt type\_error(FileName,atom)}
+ \ei
+\item {\tt FileName} has been loaded previously in the session {\em and}
+  there is more than one active thread.  
+ \bi
+ \item 	{\tt misc\_error}
+ \ei
 %
 \ei
 
@@ -512,6 +521,10 @@
 
 {\bf Error Cases}
 \bi
+\item 	{\tt FileName} is a variable
+\bi
+\item 	{\tt instantiation\_error}
+\ei
 \item 	{\tt FileName} is not an atom:
 \bi
 \item 	{\tt type\_error(FileName,atom)}
@@ -523,6 +536,11 @@
 \item 	{\tt domain\_error(a\_or\_z,Dir)}
 \ei
 %
+\item {\tt FileName} has been loaded previously in the session {\em and}
+  there is more than one active thread.  
+\bi
+\item 	{\tt misc\_error}
+\ei
 \ei
 
 \ouritem{load\_dync(+FileName)}\index{\texttt{load\_dync/1}}
@@ -559,11 +577,20 @@
 
 {\bf Error Cases}
 \bi
+\item 	{\tt FileName} is a variable
+\bi
+\item 	{\tt instantiation\_error}
+\ei
 \item 	{\tt FileName} is not an atom.
 \bi
 \item 	{\tt type\_error(FileName,atom)}
 \ei
 %
+\item {\tt FileName} has been loaded previously in the session {\em and}
+  there is more than one active thread.  
+\bi
+\item 	{\tt misc\_error}
+\ei
 \ei
 
 \ournewitem{load\_dync(+FileName,+Dir)}{consult}
@@ -593,6 +620,10 @@
 
 {\bf Error Cases}
 \bi
+\item 	{\tt FileName} is a variable
+\bi
+\item 	{\tt instantiation\_error}
+\ei
 \item 	{\tt FileName} is not an atom:
 \bi
 \item 	{\tt type\_error(FileName,atom)}
@@ -604,6 +635,11 @@
 \item 	{\tt domain\_error(a\_or\_z,Dir)}
 \ei
 %
+\item {\tt FileName} has been loaded previously in the session {\em and}
+  there is more than one active thread.  
+\bi
+\item 	{\tt misc\_error}
+\ei
 \ei
 
 \ouritem{ensure\_loaded(+FileName,+Action)}
@@ -633,6 +669,10 @@
 
 {\bf Error Cases}
 \bi
+\item 	{\tt FileName} is not instantiated:
+\bi
+\item 	{\tt instantiation\_error}
+\ei
 \item 	{\tt FileName} is not an atom:
 \bi
 \item 	{\tt type\_error(FileName,atom)}

Index: system.tex
===================================================================
RCS file: /cvsroot/xsb/XSB/docs/userman/system.tex,v
retrieving revision 1.52
retrieving revision 1.53
diff -u -r1.52 -r1.53
--- system.tex	26 Dec 2005 17:14:43 -0000	1.52
+++ system.tex	24 Jan 2006 23:37:55 -0000	1.53
@@ -825,13 +825,31 @@
 predicates of that module are imported into the current environment
 (the current working module {\tt usermod}) if the file is a module.
 For non-modules, all predicates are imported into the current working
-module.
-
-Finally any queries --- that is, any terms with principal functor {\tt
-'?-'/1}, or with the principal functor {\tt ':-'/1} and that are not
-directives like the ones described in Section~\ref{the_compiler} 
-are executed in the order that they are encountered.
+module.  As the last part of loading, any queries --- that is, any
+terms with principal functor {\tt '?-'/1}, or with the principal
+functor {\tt ':-'/1} and that are not directives like the ones
+described in Section~\ref{the_compiler} are executed in the order that
+they are encountered.
+
+Error conditions for {\tt consult(+File)} are as follows: 
+\bi
+\item 	{\tt File} is not instantiated
+\bi
+\item 	{\tt instantiation\_error}
+\ei
+%
+\item 	{\tt File} is not an atom
+\bi
+\item 	{\tt type\_error(atom,File)}
+\ei
+%
+\item {\tt File} has been loaded previously in the session {\em and}
+  there is more than one active thread.  \bi
+\item 	{\tt misc\_error}
+\ei
+\ei
 
+\paragraph*{The multifile directive}
 \index{\texttt{multifile/2}}
 The default action upon loading a file or module is to delete all
 previous byte-code for predicates defined in the file.  If this is not