# HG changeset patch
# User Adam Chlipala <adam@chlipala.net>
# Date 1306847643 14400
# Node ID a354b306f948d09794d64474ad866ce64e9bf5f5
# Parent  4d04cb89649b98b1cf0d38361f4187e9aac1ff9b
Explain how to signal an error in a commit handler

diff -r 4d04cb89649b -r a354b306f948 doc/manual.tex
--- a/doc/manual.tex	Tue May 31 07:44:52 2011 -0400
+++ b/doc/manual.tex	Tue May 31 09:14:03 2011 -0400
@@ -2192,6 +2192,11 @@
   All pointers to the context-local heap (see description below of \texttt{uw\_malloc()}) become invalid at the start and end of any execution of a main entry point function of an application.  For example, if the request handler is restarted because of a \texttt{uw\_error()} call with \texttt{BOUNDED\_RETRY} or for any other reason, it is unsafe to access any local heap pointers that may have been stashed somewhere beforehand.
 
   \item \begin{verbatim}
+void uw_set_error_message(uw_context, const char *fmt, ...);
+  \end{verbatim}
+  This simpler form of \texttt{uw\_error()} saves an error message without immediately aborting execution.
+
+  \item \begin{verbatim}
 void uw_push_cleanup(uw_context, void (*func)(void *), void *arg);
 void uw_pop_cleanup(uw_context);
   \end{verbatim}
@@ -2220,6 +2225,8 @@
 
   It is not safe for any of these handlers to access a context-local heap through a pointer returned previously by \texttt{uw\_malloc()}, nor should any new calls to that function be made.  Think of the context-local heap as meant for use by the Ur/Web code itself, while transactional handlers execute after the Ur/Web code has finished.
 
+  A handler may signal an error by calling \texttt{uw\_set\_error\_message()}, but it is not safe to call \texttt{uw\_error()} from a handler.  Signaling an error in a commit handler will cause the runtime system to switch to aborting the transaction, immediately after the current commit handler returns.
+
   \item \begin{verbatim}
 void *uw_get_global(uw_context, char *name);
 void uw_set_global(uw_context, char *name, void *data, uw_callback free);