#lang scribble/doc
@(require "web-server.rkt"
          (for-label racket/serialize
                     web-server/lang/abort-resume
                     web-server/lang/web))

@title[#:tag "considerations"]{Usage Considerations}

A stateless servlet has the following process performed on it
automatically:
@itemize[
 @item{All uses of @racket[letrec] are removed and replaced with
       equivalent uses of @racket[let] and imperative features.}
 @item{The program is converted into @link["http://en.wikipedia.org/wiki/Administrative_normal_form"]{ANF} (Administrative Normal Form),
       making all continuations explicit.}
 @item{All continuations and continuations marks are recorded in the
       continuation marks of the expression
       they are the continuation of.}
 @item{All calls to external modules are identified and marked.}
 @item{All uses of @racket[call/cc] are removed and replaced with
       equivalent gathering of the continuations through the continuation marks installed earlier.}
 @item{The program is defunctionalized with a serializable data-structure for each
       @racket[lambda].}
]

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.

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.

First, this process drastically changes the structure of your program.
It will create an immense number of lambdas and structures your program
did not normally contain. The performance implication of this has not
been studied with Racket.

Second, the defunctionalization process is sensitive to the syntactic
structure of your program. Therefore, if you change your program in a
trivial way, for example, changing a constant, then all serialized
continuations will be obsolete and will error when deserialization is
attempted. This is a feature, not a bug! It is a small price to pay for
protection from the sorts of errors that would occur if your program
were changed in a meaningful way.

Third, the values in the lexical scope of your continuations must be
serializable for the continuations itself to be serializable. This means
that you must use @racket[define-serializable-struct] rather than
@racket[define-struct], and take care to use modules that do the same.
Similarly, you may not use @racket[parameterize], because
parameterizations are not serializable.

Fourth, and related, this process only runs on your code, not on the
code you @racket[require]. Thus, your continuations---to be
serializable---must not be in the context of another module. For
example, the following will fail with an @as-index{"unsafe context"}
exception:

@racketblock[
 (define requests
   (map (lambda (rg) (send/suspend/url rg))
        response-generators))
]
because @racket[map] is not transformed by the process. However, if you defined
your own @racket[map] function, there would be no problem. Another solution is to
store the @racket[map] part of the continuation on the server with @racket[serial->native]
and @racket[native->serial]:
@racketblock[
 (define requests
   (serial->native
    (map (lambda (rg) (native->serial (send/suspend/url rg)))
        response-generators)))
]

Fifth, the store is @bold{not} serialized. If you rely on the store you will
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 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.