Mercurial > urweb
comparison doc/manual.tex @ 1328:c5799b1e4c58
Update manual to track uw_register_transactional() change
| author | Adam Chlipala <adam@chlipala.net> |
|---|---|
| date | Sat, 04 Dec 2010 11:18:19 -0500 |
| parents | 127561e4aef1 |
| children | 9be9da2df74b |
comparison
equal
deleted
inserted
replaced
| 1327:1cc67fdac4d3 | 1328:c5799b1e4c58 |
|---|---|
| 2137 | 2137 |
| 2138 For performance and correctness reasons, it is usually preferable to use \texttt{uw\_malloc()} instead of \texttt{malloc()}. The former manipulates a local heap that can be kept allocated across page requests, while the latter uses global data structures that may face contention during concurrent execution. | 2138 For performance and correctness reasons, it is usually preferable to use \texttt{uw\_malloc()} instead of \texttt{malloc()}. The former manipulates a local heap that can be kept allocated across page requests, while the latter uses global data structures that may face contention during concurrent execution. |
| 2139 | 2139 |
| 2140 \item \begin{verbatim} | 2140 \item \begin{verbatim} |
| 2141 typedef void (*uw_callback)(void *); | 2141 typedef void (*uw_callback)(void *); |
| 2142 typedef void (*uw_callback_with_retry)(void *, int will_retry); | |
| 2142 void uw_register_transactional(uw_context, void *data, uw_callback commit, | 2143 void uw_register_transactional(uw_context, void *data, uw_callback commit, |
| 2143 uw_callback rollback, uw_callback free); | 2144 uw_callback rollback, uw_callback_with_retry free); |
| 2144 \end{verbatim} | 2145 \end{verbatim} |
| 2145 All side effects in Ur/Web programs need to be compatible with transactions, such that any set of actions can be undone at any time. Thus, you should not perform actions with non-local side effects directly; instead, register handlers to be called when the current transaction is committed or rolled back. The arguments here give an arbitary piece of data to be passed to callbacks, a function to call on commit, a function to call on rollback, and a function to call afterward in either case to clean up any allocated resources. A rollback handler may be called after the associated commit handler has already been called, if some later part of the commit process fails. | 2146 All side effects in Ur/Web programs need to be compatible with transactions, such that any set of actions can be undone at any time. Thus, you should not perform actions with non-local side effects directly; instead, register handlers to be called when the current transaction is committed or rolled back. The arguments here give an arbitary piece of data to be passed to callbacks, a function to call on commit, a function to call on rollback, and a function to call afterward in either case to clean up any allocated resources. A rollback handler may be called after the associated commit handler has already been called, if some later part of the commit process fails. A free handler is told whether the runtime system expects to retry the current page request after rollback finishes. |
| 2146 | 2147 |
| 2147 Any of the callbacks may be \texttt{NULL}. To accommodate some stubbornly non-transactional real-world actions like sending an e-mail message, Ur/Web treats \texttt{NULL} \texttt{rollback} callbacks specially. When a transaction commits, all \texttt{commit} actions that have non-\texttt{NULL} rollback actions are tried before any \texttt{commit} actions that have \texttt{NULL} rollback actions. Thus, if a single execution uses only one non-transactional action, and if that action never fails partway through its execution while still causing an observable side effect, then Ur/Web can maintain the transactional abstraction. | 2148 Any of the callbacks may be \texttt{NULL}. To accommodate some stubbornly non-transactional real-world actions like sending an e-mail message, Ur/Web treats \texttt{NULL} \texttt{rollback} callbacks specially. When a transaction commits, all \texttt{commit} actions that have non-\texttt{NULL} rollback actions are tried before any \texttt{commit} actions that have \texttt{NULL} rollback actions. Thus, if a single execution uses only one non-transactional action, and if that action never fails partway through its execution while still causing an observable side effect, then Ur/Web can maintain the transactional abstraction. |
| 2148 | 2149 |
| 2149 \item \begin{verbatim} | 2150 \item \begin{verbatim} |
| 2150 void *uw_get_global(uw_context, char *name); | 2151 void *uw_get_global(uw_context, char *name); |