From c3103d21929dd36e4d68f5e551648966130ae943 Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Sun, 3 Jun 2007 05:39:34 +0000 Subject: [PATCH] Working on documentation svn: r6465 --- .../docs/reference/command-line.scrbl | 13 +++ .../web-server/docs/reference/managers.scrbl | 84 ++++++++++++++++++- .../web-server/docs/reference/reference.scrbl | 1 + collects/web-server/managers/none.ss | 2 +- 4 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 collects/web-server/docs/reference/command-line.scrbl diff --git a/collects/web-server/docs/reference/command-line.scrbl b/collects/web-server/docs/reference/command-line.scrbl new file mode 100644 index 0000000000..4a49a33802 --- /dev/null +++ b/collects/web-server/docs/reference/command-line.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Command-line Tools} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/managers.scrbl b/collects/web-server/docs/reference/managers.scrbl index 60bd7f5b67..c4061d2ebd 100644 --- a/collects/web-server/docs/reference/managers.scrbl +++ b/collects/web-server/docs/reference/managers.scrbl @@ -3,11 +3,91 @@ @title[#:style 'toc]{Continuation Managers} -XXX +Since Scheme servlets store their continuations on the server, they take +up memory on the server. Furthermore, garbage collection can not be used +to free this memory, because there are roots outside the system: users' +browsers, bookmarks, brains, and notebooks. Therefore, some other strategy +must be used if memory usage is to be controlled. This functionality is +pluggable through the manager interface. @local-table-of-contents[] @; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@section[#:tag "manager"]{General} + +@file{managers/manager.ss} defines the manager interface. It is required by +the users and implementers of managers. + +@defstruct[manager ([create-instance (any/c (-> void) . -> . number?)] + [adjust-timeout! (number? number? . -> . void)] + [instance-lookup-data (number? . -> . any/c)] + [instance-lock! (number? . -> . void)] + [instance-unlock! (number? . -> . void)] + [clear-continuations! (number? . -> . void)] + [continuation-store! (number? any/c expiration-handler? . -> . (list/c number? number?))] + [continuation-lookup (number? number? number? . -> . any/c)])]{ + @scheme[create-instance] is called to initialize a instance, to hold the + continuations of one servlet session. It is passed some arbitrary data and + a function to call when the instance is expired. It runs the id of the + instance. + + @scheme[adjust-timeout!] is a to-be-deprecated function that takes an + instance-id and a number. It is specific to the timeout-based manager + and will be removed. + + @scheme[instance-lookup-data] accesses the arbitrary data passed into + @scheme[create-instance] match by the given instance-id. + + @scheme[instance-lock!] and @scheme[instance-unlock!] lock and unlock + access to a particular instance. + + @scheme[clear-continuations!] expires all the continuations of an instance. + + @scheme[continuation-store!] is given an instance-id, a continuation value, + and a function to include in the exception thrown if the continuation is + looked up and has been expired. The two numbers returned are a + continuation-id and a random nonce. + + @scheme[continuation-lookup] finds the continuation value associated with + the instance-id, continuation-id, and nonce triple it is given. +} + +@defstruct[(exn:fail:servlet-manager:no-instance exn:fail) + ([message string?] + [continuation-marks continuation-mark-set?] + [expiration-handler expiration-handler?])]{ + This exception should be thrown by a manager when an instance is looked + up that does not exist. +} + +@defstruct[(exn:fail:servlet-manager:no-continuation exn:fail) + ([message string?] + [continuation-marks continuation-mark-set?] + [expiration-handler expiration-handler?])]{ + This exception should be thrown by a manager when a continuation is + looked up that does not exist. +} + +@; ------------------------------------------------------------ +@section[#:tag "none"]{No Continuations} + +@file{managers/none.ss} defines a manager constructor: + +@defproc[(create-none-manager (instance-expiration-handler expiration-handler?)) + manager?]{ + This manager does not actually store any continuation or instance data. + You could use it if you know your servlet does not use the continuation + capturing functions and want the server to not allocate meta-data + structures for each instance. +} + +If you are considering using this manager, also consider using the +Web Language. (See @secref["lang"].) + +@; ------------------------------------------------------------ +@section[#:tag "timeouts"]{Timeouts} + +@; ------------------------------------------------------------ +@section[#:tag "lru"]{LRU} XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/reference.scrbl b/collects/web-server/docs/reference/reference.scrbl index 7900de810f..24f4401419 100644 --- a/collects/web-server/docs/reference/reference.scrbl +++ b/collects/web-server/docs/reference/reference.scrbl @@ -8,6 +8,7 @@ develop Web applications in Scheme. @table-of-contents[] +@include-section["command-line.scrbl"] @include-section["configuration.scrbl"] @include-section["dispatchers.scrbl"] @include-section["lang.scrbl"] diff --git a/collects/web-server/managers/none.ss b/collects/web-server/managers/none.ss index 432266cbc3..9d2d887067 100644 --- a/collects/web-server/managers/none.ss +++ b/collects/web-server/managers/none.ss @@ -47,4 +47,4 @@ continuation-store! continuation-lookup ; Specific - instance-expiration-handler))) + instance-expiration-handler))) \ No newline at end of file