From 3498ac8744a09886ff93247cce14baad68f9a496 Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Thu, 16 Sep 2010 11:44:54 -0600 Subject: [PATCH] Doc rearrange re Robby --- collects/web-server/scribblings/lang-api.scrbl | 2 +- .../web-server/scribblings/servlet-env.scrbl | 18 ++++++++++++------ .../scribblings/stateless-usage.scrbl | 15 +++++++++++---- 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/collects/web-server/scribblings/lang-api.scrbl b/collects/web-server/scribblings/lang-api.scrbl index 8472f274d7..452fd28cee 100644 --- a/collects/web-server/scribblings/lang-api.scrbl +++ b/collects/web-server/scribblings/lang-api.scrbl @@ -61,6 +61,7 @@ These servlets have an extensive API available to them: @racketmodname[net/url], @racketmodname[web-server/stuffers]. Some of these are documented in the subsections that follow. +@include-section["stateless-usage.scrbl"] @include-section["serial.scrbl"] @include-section["native.scrbl"] @include-section["lang.scrbl"] @@ -69,4 +70,3 @@ These servlets have an extensive API available to them: @racketmodname[net/url], @include-section["web-param.scrbl"] @include-section["soft.scrbl"] @include-section["stuffers.scrbl"] -@include-section["stateless-usage.scrbl"] diff --git a/collects/web-server/scribblings/servlet-env.scrbl b/collects/web-server/scribblings/servlet-env.scrbl index 205291bdbd..d325de9ccc 100644 --- a/collects/web-server/scribblings/servlet-env.scrbl +++ b/collects/web-server/scribblings/servlet-env.scrbl @@ -1,8 +1,7 @@ #lang scribble/doc @(require "web-server.rkt") -@title[#:tag "servlet-env" - #:style 'toc]{Simple Single Servlet Servers} +@title[#:tag "servlet-env"]{Simple Single Servlet Servers} @(require (for-label web-server/servlet-env web-server/http web-server/managers/lru @@ -17,9 +16,13 @@ web-server/stuffers racket/list)) -@defmodule[web-server/servlet-env]{ +@defmodule[web-server/servlet-env] -The @web-server provides a way to quickly configure and start a servlet with more customizability than @racketmodname[web-server/insta] provides. This is provided by the @racketmodname[web-server/servlet-env] module. Here is a simple example of its use: +The @web-server provides a way to quickly configure and start a servlet with more customizability than @racketmodname[web-server/insta] provides. This is provided by the @racketmodname[web-server/servlet-env] module. + +@section{Examples} + +Here is a simple example of its use: @racketmod[ racket (require web-server/servlet @@ -94,6 +97,8 @@ and don't want a browser opened or the DrRacket banner printed, then you can wri #:command-line? #t) ] +@subsection{Stateless Servlets} + Suppose you would like to start a server for a stateless Web servlet @filepath{servlet.rkt} that provides @racketid[start]: @racketmod[ racket @@ -123,6 +128,8 @@ every time the continuation link is clicked, @racket[serve/servlet] will run and attempt to start a Web server instance and open a browser window. These problems do not occur if your servlet is saved in a file and if @racket[serve/servlet] is run in another module. +@section{Full API} + @defproc[(serve/servlet [start (request? . -> . response/c)] [#:command-line? command-line? boolean? #f] [#:connection-close? connection-close? boolean? #f] @@ -210,5 +217,4 @@ and if @racket[serve/servlet] is run in another module. If @racket[connection-close?] is @racket[#t], then every connection is closed after one request. Otherwise, the client decides based on what HTTP version it uses. } - -} + \ No newline at end of file diff --git a/collects/web-server/scribblings/stateless-usage.scrbl b/collects/web-server/scribblings/stateless-usage.scrbl index 276f3bd84c..3b4c397c82 100644 --- a/collects/web-server/scribblings/stateless-usage.scrbl +++ b/collects/web-server/scribblings/stateless-usage.scrbl @@ -24,9 +24,14 @@ A stateless servlet has the following process performed on it automatically: This process allows the continuations captured by your servlet to be serialized. This means they may be stored on the client's browser or the server's disk. -Thus, your servlet has no cost to the server other than execution. This is + +This means your servlet has no cost to the server other than execution. This is very attractive if you've used Racket servlets and had memory problems. +This means your server can restart in the middle of a long running Web interaction +without the URLs that have been shared with the client expiring. This is +very attractive if you've used Racket servlets and had session timeout problems. + This process is defined on all of Racket and occurs after macro-expansion, so you are free to use all interesting features of Racket. However, there are some considerations you must make. @@ -75,7 +80,9 @@ be taking huge risks. You will be assuming that the serialized continuation is invoked on the same server before the server is restarted or the memory is garbage collected. -This process is derived from the ICFP papers -@emph{@link["http://www.cs.brown.edu/~sk/Publications/Papers/Published/pcmkf-cont-from-gen-stack-insp/"]{Continuations from Generalized Stack Inspection}} by Pettyjohn et al. in 2005 and -@emph{Automatically RESTful Web Applications, Or Marking Modular Serializable Continuations} by Jay McCarthy in 2009. +This process is derived from the papers +@emph{@link["http://www.cs.brown.edu/~sk/Publications/Papers/Published/pcmkf-cont-from-gen-stack-insp/"]{Continuations from Generalized Stack Inspection}} by Pettyjohn et al. in 2005, +@emph{@link["http://faculty.cs.byu.edu/~jay/static/icfp065-mccarthy.pdf"]{Automatically RESTful Web Applications, Or Marking Modular Serializable Continuations}} by Jay McCarthy in 2009, +and +@emph{@link["http://faculty.cs.byu.edu/~jay/static/oopsla026-mccarthy.pdf"]{The Two-State Solution: Native and Serializable Continuations Accord}} by Jay McCarthy in 2010, We thank Greg Pettyjohn for his initial implementation of this algorithm.