Mercurial > urweb

comparison doc/manual.tex @ 1469:a354b306f948

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Explain how to signal an error in a commit handler
author Adam Chlipala <adam@chlipala.net>
date Tue, 31 May 2011 09:14:03 -0400
parents 2f5fd248588d
children 18d18a70821e
comparison
equal deleted inserted replaced
1468:4d04cb89649b 1469:a354b306f948
2190 Abort the current request processing, giving a \texttt{printf}-style format string and arguments for generating an error message. The \texttt{failure\_kind} argument can be \texttt{FATAL}, to abort the whole execution; \texttt{BOUNDED\_RETRY}, to try processing the request again from the beginning, but failing if this happens too many times; or \texttt{UNLIMITED\_RETRY}, to repeat processing, with no cap on how many times this can recur. 2190 Abort the current request processing, giving a \texttt{printf}-style format string and arguments for generating an error message. The \texttt{failure\_kind} argument can be \texttt{FATAL}, to abort the whole execution; \texttt{BOUNDED\_RETRY}, to try processing the request again from the beginning, but failing if this happens too many times; or \texttt{UNLIMITED\_RETRY}, to repeat processing, with no cap on how many times this can recur.
2191 2191
2192 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. 2192 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.
2193 2193
2194 \item \begin{verbatim} 2194 \item \begin{verbatim}
2195 void uw_set_error_message(uw_context, const char *fmt, ...);
2196 \end{verbatim}
2197 This simpler form of \texttt{uw\_error()} saves an error message without immediately aborting execution.
2198
2199 \item \begin{verbatim}
2195 void uw_push_cleanup(uw_context, void (*func)(void *), void *arg); 2200 void uw_push_cleanup(uw_context, void (*func)(void *), void *arg);
2196 void uw_pop_cleanup(uw_context); 2201 void uw_pop_cleanup(uw_context);
2197 \end{verbatim} 2202 \end{verbatim}
2198 Manipulate a stack of actions that should be taken if any kind of error condition arises. Calling the ``pop'' function both removes an action from the stack and executes it. It is a bug to let a page request handler finish successfully with unpopped cleanup actions. 2203 Manipulate a stack of actions that should be taken if any kind of error condition arises. Calling the ``pop'' function both removes an action from the stack and executes it. It is a bug to let a page request handler finish successfully with unpopped cleanup actions.
2199 2204
2218 2223
2219 When a request handler ends with multiple pending transactional actions, their handlers are run in a first-in-last-out stack-like order, wherever the order would otherwise be ambiguous. 2224 When a request handler ends with multiple pending transactional actions, their handlers are run in a first-in-last-out stack-like order, wherever the order would otherwise be ambiguous.
2220 2225
2221 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. 2226 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.
2222 2227
2228 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.
2229
2223 \item \begin{verbatim} 2230 \item \begin{verbatim}
2224 void *uw_get_global(uw_context, char *name); 2231 void *uw_get_global(uw_context, char *name);
2225 void uw_set_global(uw_context, char *name, void *data, uw_callback free); 2232 void uw_set_global(uw_context, char *name, void *data, uw_callback free);
2226 \end{verbatim} 2233 \end{verbatim}
2227 Different FFI-based extensions may want to associate their own pieces of data with contexts. The global interface provides a way of doing that, where each extension must come up with its own unique key. The \texttt{free} argument to \texttt{uw\_set\_global()} explains how to deallocate the saved data. It is never safe to store \texttt{uw\_malloc()}ed pointers in global variable slots. 2234 Different FFI-based extensions may want to associate their own pieces of data with contexts. The global interface provides a way of doing that, where each extension must come up with its own unique key. The \texttt{free} argument to \texttt{uw\_set\_global()} explains how to deallocate the saved data. It is never safe to store \texttt{uw\_malloc()}ed pointers in global variable slots.