From 4330e7007078d680c1a3092d77831ed0c0fcf9b7 Mon Sep 17 00:00:00 2001 From: Adam Chlipala Date: Fri, 26 Aug 2016 12:41:25 -0400 Subject: Manual: explain the cooperative multithreading model --- doc/manual.tex | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'doc/manual.tex') diff --git a/doc/manual.tex b/doc/manual.tex index 76f69330..8c12102e 100644 --- a/doc/manual.tex +++ b/doc/manual.tex @@ -2095,6 +2095,12 @@ Configure the policy for meta names with the \texttt{allow} and \texttt{deny} \t Ur/Web supports running code on web browsers, via automatic compilation to JavaScript. +The concurrency model is \emph{cooperative multithreading}. Like with, say, POSIX threads, which uses the \emph{preemptive multithreading} model, there may be multiple threads of control active at a time. However, unlike with preemptive multithreading, the currently running thread gets to run interrupted until a well-defined \emph{context-switch} point. Specifically, four functions defined below are the context-switch points. They are $\mt{sleep}$, $\mt{rpc}$, $\mt{tryRpc}$, and $\mt{recv}$. (We explain their purposes as we come to them below.) Additional functions added via the foreign function interface might also have context-switching behavior. In any case, it is guaranteed that a running thread ``owns the processor'' until it calls a context-switching function, at which time we may switch to running a different thread instead. + +This concurrency paradigm has many nice properties. For instance, there is almost never any need for locking or other synchronization between threads. + +Readers used to the standard JavaScript model may recognize this style as the natural one that we obtain by imposing a thread-based perspective on top of the usual JavaScript callback-based API. Indeed, every context-switching Ur/Web function is implemented with an underlying JavaScript call that asks for some callback to be triggered when an event happens. + \subsubsection{The Basics} All of the functions in this subsection are client-side only. @@ -2245,7 +2251,7 @@ The $\mt{channel}$ and $\mt{send}$ operations may only be executed on the server Clients and channels live only as long as the web browser page views that they are associated with. When a user surfs away, his client and its channels will be garbage-collected, after that user is not heard from for the timeout period. Garbage collection deletes any database row that contains a client or channel directly. Any reference to one of these types inside an $\mt{option}$ is set to $\mt{None}$ instead. Both kinds of handling have the flavor of weak pointers, and that is a useful way to think about clients and channels in the database. -\emph{Note}: Currently, there are known concurrency issues with multi-threaded applications that employ message-passing on top of database engines that don't support true serializable transactions. Postgres 9.1 is the only supported engine that does this properly. +\emph{Note}: Currently, there are known concurrency issues with multi-threaded applications that employ message-passing on top of database engines that don't support true serializable transactions. Postgres (versions 9.1 and up) is the only supported engine that does this properly. \section{Ur/Web Syntax Extensions} -- cgit v1.2.3 From 6720a4578afab577f9721485fbb8e810104d6249 Mon Sep 17 00:00:00 2001 From: Adam Chlipala Date: Tue, 20 Sep 2016 14:26:58 -0400 Subject: Make HTML5 the default and add 'xhtml' .urp directive --- doc/manual.tex | 3 ++- src/compiler.sml | 3 +++ src/settings.sml | 2 +- 3 files changed, 6 insertions(+), 2 deletions(-) (limited to 'doc/manual.tex') diff --git a/doc/manual.tex b/doc/manual.tex index 8c12102e..b65809d0 100644 --- a/doc/manual.tex +++ b/doc/manual.tex @@ -151,7 +151,7 @@ Here is the complete list of directive forms. ``FFI'' stands for ``foreign func \item \texttt{exe FILENAME} sets the filename to which to write the output executable. The default for file \texttt{P.urp} is \texttt{P.exe}. \item \texttt{file URI FILENAME} asks for the application executable to respond to requests for \texttt{URI} by serving a snapshot of the contents of \texttt{FILENAME} as of compile time. That is, the file contents are baked into the executable. System file \texttt{/etc/mime.types} is consulted (again, at compile time) to figure out the right MIME type to suggest in the HTTP response. \item \texttt{ffi FILENAME} reads the file \texttt{FILENAME.urs} to determine the interface to a new FFI module. The name of the module is calculated from \texttt{FILENAME} in the same way as for normal source files. See the files \texttt{include/urweb/urweb\_cpp.h} and \texttt{src/c/urweb.c} for examples of C headers and implementations for FFI modules. In general, every type or value \texttt{Module.ident} becomes \texttt{uw\_Module\_ident} in C. -\item \texttt{html5} activates work-in-progress support for generating HTML5 instead of XHTML. For now, this option only affects the first few tokens on any page, which are always the same. +\item \texttt{html5} asks to generate HTML5 code, which primarily affects the first few lines of the output documents, like the \texttt{DOCTYPE}. This option is on by default. \item \texttt{include FILENAME} adds \texttt{FILENAME} to the list of files to be \texttt{\#include}d in C sources. This is most useful for interfacing with new FFI modules. \item \texttt{jsFile FILENAME} asks to serve the contents of a file as JavaScript. All such content is concatenated into a single file, included via a \texttt{