Doc rearrange re Robby

This commit is contained in:
Jay McCarthy 2010-09-16 11:44:54 -06:00
parent c87877349e
commit 3498ac8744
3 changed files with 24 additions and 11 deletions

View File

@ -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"]

View File

@ -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.
}
}

View File

@ -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.