From 020948cf1baf318dc37f0d7a9483de8c5e5dd5f9 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 12 Dec 2007 18:19:07 +0000 Subject: [PATCH] document the scheme/control library svn: r7971 --- collects/scribble/manual.ss | 38 +++- collects/scribblings/guide/guide.scrbl | 2 +- collects/scribblings/reference/cont.scrbl | 4 + .../scribblings/reference/control-lib.scrbl | 208 ++++++++++++++++++ .../scribblings/reference/reference.scrbl | 64 +++++- 5 files changed, 300 insertions(+), 16 deletions(-) create mode 100644 collects/scribblings/reference/control-lib.scrbl diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 7a7ea592aa..e8024a4476 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -438,6 +438,7 @@ ;; ---------------------------------------- (provide declare-exporting + deftogether defproc defproc* defstruct defthing defthing* defparam defboolparam defform defform* defform/subs defform*/subs defform/none defidform @@ -769,6 +770,24 @@ (lambda (render part ri) (proc (or (get-exporting-libraries render part ri) null))))) + + (define (*deftogether boxes . body) + (make-splice + (cons + (make-table + 'boxed + (map (lambda (box) + (unless (and (splice? box) + (= 1 (length (splice-run box))) + (table? (car (splice-run box))) + (eq? 'boxed (table-style (car (splice-run box))))) + (error 'deftogether "element is not a splice containing a single table: ~e" box)) + (list (make-flow (list (make-table #f (table-flowss (car (splice-run box)))))))) + boxes)) + body))) + + (define-syntax-rule (deftogether (box ...) . body) + (*deftogether (list box ...) . body)) (define (*defproc mode within-id stx-ids prototypes arg-contractss arg-valss result-contracts content-thunk) @@ -1581,11 +1600,22 @@ (rename-out [a-bib-entry? bib-entry?]) bibliography) - (define (cite key) - (make-link-element + (define (cite key . keys) + (make-element #f - (list (format "[~a]" key)) - `(cite ,key))) + (list "[" + (let loop ([keys (cons key keys)]) + (if (null? (cdr keys)) + (make-link-element + #f + (list (car keys)) + `(cite ,(car keys))) + (make-element + #f + (list (loop (list (car keys))) + ", " + (loop (cdr keys)))))) + "]"))) (define-struct a-bib-entry (key val)) diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl index 4d8e816217..788e730036 100644 --- a/collects/scribblings/guide/guide.scrbl +++ b/collects/scribblings/guide/guide.scrbl @@ -9,7 +9,7 @@ This guide is intended for programmers who are new to Scheme, new to PLT Scheme, or new to some part of PLT Scheme. It assumes programming experience, so if you are new to programming, consider -instead reading @|HtDP|. If you want a quick and pretty overview of PLT +instead reading @|HtDP|. If you want a brief introduction to PLT Scheme, start with @|Quick|. @seclink["to-scheme"]{Chapter 2} provides a brief introduction to diff --git a/collects/scribblings/reference/cont.scrbl b/collects/scribblings/reference/cont.scrbl index 1f0ed33953..fdd4f20d82 100644 --- a/collects/scribblings/reference/cont.scrbl +++ b/collects/scribblings/reference/cont.scrbl @@ -336,3 +336,7 @@ restore; in that case, the first step in a @scheme[pre-thunk] or (k (cons void esc))))) l) ]} + +@; ---------------------------------------------------------------------- + +@include-section["control-lib.scrbl"] diff --git a/collects/scribblings/reference/control-lib.scrbl b/collects/scribblings/reference/control-lib.scrbl new file mode 100644 index 0000000000..6ce45ebc36 --- /dev/null +++ b/collects/scribblings/reference/control-lib.scrbl @@ -0,0 +1,208 @@ +#lang scribble/doc +@require["mz.ss" + (for-label scheme/control)] + +@title{Classical Control Operators} + +@note-lib-only[scheme/control] + +The @scheme[scheme/control] library provides various control operators +from the research literature on higher-order control operators. These +control operators are implemented in terms of +@scheme[call-with-continuation-prompt], +@scheme[call-with-composable-continuations], etc., and they generally +work sensibly together. Many are redundant; for example, +@scheme[reset] and @scheme[shift] are aliases. + +@deftogether[( +@defform[(% expr)] +@defform[(% expr handler-expr)] +@defproc[(fcontrol [v any/c]) any] +)]{ + + +Sitaram's operators @cite["Sitaram93"]. + +The essential reduction rules are: + +@schemeblock[ +(% _val proc) => _val +(% _E[(fcontrol _val)] _proc) => (_proc _val (lambda (_x) _E[_x])) + (code:comment #, @t{where @scheme[_E] has no @scheme[%]}) +] + +When @scheme[handler-expr] is omitted, @scheme[%] is the same as +@scheme[prompt].} + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defform[(prompt expr ...+)] +@defform[(control id expr ...+)] +)]{ + +Among the earliest operators for higher-order control +@cite["Felleisen88" "Sitaram90"]. + +The essential reduction rules are: +@schemeblock[ +(prompt _val) => _val +(prompt _E[(control _k _expr)]) => (prompt ((lambda (_k) _expr) + (lambda (_v) _E[_v]))) + (code:comment #, @t{where @scheme[_E] has no @scheme[prompt]}) +]} + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defform[(prompt-at prompt-tag-expr expr ...+)] +@defform[(control-at prompt-tag-expr id expr ...+)] +)]{ + +Like @scheme[prompt] and @scheme[control], but using specific prompt +tags: + +@schemeblock[ +(prompt-at _tag _val) => _val +(prompt-at _tag _E[(control-at _tag _k _expr)]) => (prompt-at _tag + ((lambda (_k) _expr) + (lambda (_v) _E[_v]))) + (code:comment #, @t{where @scheme[_E] has no @scheme[prompt-at] for @scheme[_tag]}) +]} + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defform[(reset expr ...+)] +@defform[(shift id expr ...+)] +)]{ + +Danvy and Filinski's operators @cite["Danvy90"]. + +The essential reduction rules are: + +@schemeblock[ +(reset _val) => _val +(reset _E[(shift _k _expr)]) => (reset ((lambda (_k) _expr) + (lambda (_v) (reset _E[_v])))) + (code:comment #, @t{where @scheme[_E] has no @scheme[reset]}) +] + +The @scheme[reset] and @scheme[prompt] forms are interchangeable.} + + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defform[(reset-at prompt-tag-expr expr ...+)] +@defform[(shift-at prompt-tag-expr identifer expr ...+)] +)]{ + +Like @scheme[reset] and @scheme[shift], but using the specified prompt +tags.} + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defform[(prompt0 expr ...+)] +@defform[(reset0 expr ...+)] +@defform[(control0 id expr ...+)] +@defform[(shift0 id expr ...+)] +)]{ + +Generalizations of @scheme[prompt], etc. @cite["Shan04"]. + +The essential reduction rules are: + +@schemeblock[ +(prompt0 _val) => _val +(prompt0 _E[(control0 _k _expr)]) => ((lambda (_k) _expr) + (lambda (_v) _E[_v])) +(reset0 _val) => _val +(reset0 _E[(shift0 _k _expr)]) => ((lambda (_k) _expr) + (lambda (_v) (reset0 _E[_v]))) +] + +The @scheme[reset0] and @scheme[prompt0] forms are interchangable. +Furthermore, the following reductions apply: + +@schemeblock[ +(prompt _E[(control0 _k _expr)]) => (prompt ((lambda (_k) _expr) + (lambda (_v) _E[_v]))) +(reset _E[(shift0 _k _expr)]) => (reset ((lambda (_k) _expr) + (lambda (_v) (reset0 _E[_v])))) +(prompt0 _E[(control _k _expr)]) => (prompt0 ((lambda (_k) expr) + (lambda (_v) _E[_v]))) +(reset0 _E[(shift _k _expr)]) => (reset0 ((lambda (_k) expr) + (lambda (_v) (reset _E[_v])))) +] + +That is, both the @scheme[prompt]/@scheme[reset] and +@scheme[control]/@scheme[shift] sites must agree for @scheme[0]-like +behavior, otherwise the non-@scheme[0] behavior applies.} + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defform[(prompt0-at prompt-tag-expr expr ...+)] +@defform[(reset0-at prompt-tag-expr expr ...+)] +@defform[(control0-at prompt-tag-expr id expr ...+)] +@defform[(shift0-at prompt-tag-expr id expr ...+)] +)]{ + +Variants of @scheme[prompt0], @|etc| that accept a prompt tag.} + +@; ---------------------------------------------------------------------- + +@defproc[(spawn [proc ((any/c . -> . any) . -> . any)]) any]{ + +The operators of Hieb and Dybvig @cite["Hieb90"]. + +The essential reduction rules are: + +@schemeblock[ +(prompt-at _tag _obj) => _obj +(spawn _proc) => (prompt _tag (_proc (lambda (_x) (abort _tag _x)))) +(prompt-at _tag _E[(abort _tag _proc)]) + => (_proc (lambda (_x) (prompt-at _tag _E[_x]))) + (code:comment #, @t{where @scheme[_E] has no @scheme[prompt-at] for @scheme[_tag]}) +]} + +@; ---------------------------------------------------------------------- + +@defproc[(splitter [proc (((-> any) . -> . any) + ((continuation? . -> . any) . -> . any) + . -> . any)]) + any]{ + +The operator of Queinnec and Serpette @cite["Queinnec91"]. + +The essential reduction rules are: +@schemeblock[ +(splitter _proc) => (prompt-at _tag + (_proc (lambda (_thunk) + (abort _tag _thunk)) + (lambda (_proc) + (control0-at _tag _k (_proc _k))))) +(prompt-at _tag _E[(abort _tag _thunk)]) => (_thunk) + (code:comment #, @t{where @scheme[_E] has no @scheme[prompt-at] for @scheme[_tag]}) +(prompt-at _tag _E[(control0-at _tag _k _expr)]) => ((lambda (_k) _expr) + (lambda (_x) _E[_x])) + (code:comment #, @t{where @scheme[_E] has no @scheme[prompt-at] for @scheme[_tag]}) +]} + +@; ---------------------------------------------------------------------- + +@deftogether[( +@defproc[(new-prompt) any] +@defform[(set prompt-expr expr ...+)] +@defform[(cupto prompt-expr id expr ...+)] +)]{ + +The operators of Gunter et al. @cite["Gunter95"]. + +In this library, @scheme[new-prompt] is an alias for +@scheme[make-continuation-prompt-tag], @scheme[set] is an alias for +@scheme[prompt0-at], and @scheme[cupto] is an alias for @scheme[control0-at]. + +} diff --git a/collects/scribblings/reference/reference.scrbl b/collects/scribblings/reference/reference.scrbl index 53b18b1e73..53cb175eff 100644 --- a/collects/scribblings/reference/reference.scrbl +++ b/collects/scribblings/reference/reference.scrbl @@ -49,11 +49,17 @@ This chapter provides some temporary hyper-link targets. @(bibliography - (bib-entry #:key "Sitaram93" - #:title "Handling Control" - #:author "Dorai Sitaram" - #:location "Programming Language Design and Implementation" - #:date 1993) + (bib-entry #:key "Danvy90" + #:author "Olivier Danvy and Andre Filinski" + #:title "Abstracting Control" + #:location "LISP and Functional Programming" + #:date "1990") + + (bib-entry #:key "Felleisen88" + #:author "Matthias Felleisen, Mitch Wand, Dan Friedman, and Bruce Duba" + #:title "Abstract Continuations: A Mathematical Semantics for Handling Full Functional Jumps" + #:location "LISP and Functional Programming" + #:date "1988") (bib-entry #:key "Friedman95" #:title "Exception system proposal" @@ -62,6 +68,48 @@ This chapter provides some temporary hyper-link targets. #:url "http://www.cs.indiana.edu/scheme-repository/doc.proposals.exceptions.html" #:date "1995") + (bib-entry #:key "Gasbichler02" + #:title "Processes vs. User-Level Threads in Scsh" + #:author "Martin Gasbichler and Michael Sperber" + #:date 2002 + #:location "Workshop on Scheme and Functional Programming") + + (bib-entry #:key "Gunter95" + #:author "Carl Gunter, Didier Remy, and Jon Rieke" + #:title "A Generalization of Exceptions and Control in ML-like Languages" + #:location "Functional Programming Languages and Computer Architecture" + #:date 1995) + + (bib-entry #:key "Hieb90" + #:author "Robert Hieb and R. Kent Dybvig" + #:title "Continuations and Concurrency" + #:location "Principles and Practice of Parallel Programming" + #:date "1990") + + (bib-entry #:key "Queinnec91" + #:author "Queinnec and Serpette" + #:title "A Dynamic Extent Control Operator for Partial Continuations" + #:location "Principles of Programming Languages" + #:date "1991") + + (bib-entry #:key "Shan04" + #:author "Ken Shan" + #:title "Shift to Control" + #:location "Workshop on Scheme and Functional Programming" + #:date 2004) + + (bib-entry #:key "Sitaram90" + #:author "Dorai Sitaram" + #:title "Control Delimiters and Their Hierarchies" + #:location @italic{Lisp and Symbolic Computation} + #:date "1990") + + (bib-entry #:key "Sitaram93" + #:title "Handling Control" + #:author "Dorai Sitaram" + #:location "Programming Language Design and Implementation" + #:date "1993") + (bib-entry #:key "SRFI-42" #:title "SRFI-42: Eager Comprehensions" #:author "Sebastian Egner" @@ -69,12 +117,6 @@ This chapter provides some temporary hyper-link targets. #:url "http://srfi.schemers.org/srfi-42/" #:date "2003") - (bib-entry #:key "Gasbichler02" - #:title "Processes vs. User-Level Threads in Scsh" - #:author "Martin Gasbichler and Michael Sperber" - #:date 2002 - #:location "Scheme Workshop") - ) @;------------------------------------------------------------------------