move future-visualizer docs out of the Reference

collects/future-visualizer/info.rkt

@@ -0,0 +1,4 @@
+#lang setup/infotab
+
+(define scribblings
+  '(("scribblings/future-visualizer.scrbl" (multi-page) (tool))))

collects/future-visualizer/scribblings/common.rkt

@@ -0,0 +1,23 @@
+#lang racket
+
+(require (for-label racket/base)
+         scribble/manual
+         scribble/decode)
+
+(provide (for-label (all-from-out racket/base))
+         (all-from-out scribble/manual)
+         guideintro
+         refsecref)
+
+(define (refsecref s)
+  (secref #:doc '(lib "scribblings/reference/reference.scrbl") s))
+
+(define (guidesecref s)
+  (secref #:doc '(lib "scribblings/guide/guide.scrbl") s))
+
+(define Guide
+  (other-manual '(lib "scribblings/guide/guide.scrbl")))
+
+(define (guideintro tag . s)
+  (apply margin-note
+         (decode-content (append (list (guidesecref tag) " in " Guide " introduces ")))))

collects/future-visualizer/scribblings/future-visualizer.scrbl

@@ -1,5 +1,7 @@
 #lang scribble/doc 
-@(require "mz.rkt" (for-label future-visualizer/trace racket/future)) 
+@(require "common.rkt" (for-label future-visualizer
+                                  future-visualizer/trace
+                                  racket/future)) 
 
 @title[#:tag "futures-visualizer"]{Futures Visualizer} 
 
@@ -70,7 +72,7 @@ and all events associated with its futures, with OS-level threads
 or @deftech{processes} organized along the y-axis and time increasing along 
 the x-axis.  Garbage collections are shown as translucent maroon bars spanning 
 the height of the timeline.  A coloring convention is used to distinguish between 
-different types of events (see @secref["future-logging"] for a full 
+different types of events (see @refsecref["future-logging"] for a full 
 description of these event types): 
 
 @itemlist[ 
@@ -140,3 +142,7 @@ and is denoted @deftech{RTT}.
   between each depth and horizontally between siblings.  The @racket[zoom] argument specifies the zoom factor for the 
   tree image in the range 1-5, where 5 returns a 500% zoom.
 }
+
+@; ----------------------------------------
+
+@include-section["futures-trace.scrbl"]

collects/future-visualizer/scribblings/futures-trace.scrbl

@@ -0,0 +1,100 @@
+#lang scribble/doc 
+@(require "common.rkt" (for-label racket/future future-visualizer/trace)) 
+
+@title[#:tag "futures-trace"]{Futures Tracing} 
+
+@defmodule[future-visualizer/trace]
+
+The @deftech{futures trace} module exposes low-level information about 
+the execution of parallel programs written using @racket[future].   
+
+
+@deftogether[(
+  @defform[(trace-futures e ...)] 
+  @defproc[(trace-futures-thunk [thunk (-> any)]) (listof indexed-future-event?)]
+)]{
+ The @racket[trace-futures] macro and @racket[trace-futures-thunk] function 
+ track the execution of a program using futures and return the program 
+ trace as a list of @racket[indexed-future-event] structures.
+ 
+ This program:
+ 
+ @racketblock[ 
+    (require racket/future 
+             future-visualizer/trace) 
+     
+    (trace-futures  
+     (let ([f (future (lambda () ...))]) 
+       ... 
+       (touch f)))
+ ]
+ 
+ Is equivalent to:
+ 
+ @racketblock[ 
+    (require racket/future 
+             future-visualizer/trace) 
+                                      
+    (start-future-tracing!) 
+    (let ([f (future (lambda () ...))]) 
+      ... 
+      (touch f)) 
+    (stop-future-tracing!)
+    (timeline-events)
+ ]
+}
+
+@deftogether[(
+  @defproc[(start-future-tracing!) void?]
+  @defproc[(stop-future-tracing!) void?]
+  @defproc[(timeline-events) (listof indexed-future-event?)]
+)]{
+ The @racket[start-future-tracing!] procedure enables the collection 
+ of future-related execution data.  This function should be called immediately 
+ prior to executing code the programmer wishes to profile. 
+ 
+ The @racket[stop-future-tracing!] procedure must be used to indicate the 
+ end of code the programmer wishes to trace.  Tracing works by simply using a 
+ log receiver to record all future-related log events; this procedure logs a 
+ special message that is well-known to the log receiver to mean 'stop recording'.
+ 
+ The @racket[timeline-events] procedure returns the program trace as 
+ a list of @racket[indexed-future-event] structures. 
+}
+  
+@defstruct[indexed-future-event ([index exact-nonnegative-integer?] 
+                                 [event (or future-event? gc-info?)])]{
+  Represents an individual log message in a program trace.  In addition to 
+  future events, the tracing code also records garbage collection events; hence 
+  the @racket[event] field may contain either a @racket[future-event] or @racket[gc-info], 
+  where the latter describes a GC operation.  Because multiple 
+  @racket[future-event] structures may contain identical timestamps, the 
+  @racket[index] field ranks them in the order in which they were recorded 
+  in the log output.
+}
+                                                                      
+@defstruct[future-event ([future-id (or exact-nonnegative-integer? #f)]
+                         [proc-id exact-nonnegative-integer?] 
+                         [action symbol?] 
+                         [time-id real?] 
+                         [prim-name (or symbol? #f)] 
+                         [user-data (or #f symbol? exact-nonnegative-integer?)]) 
+                        #:prefab]{
+ Represents a future event as logged by the run-time system. See
+@refsecref["future-logging"] for more information.}
+  
+@defstruct[gc-info ([major? boolean?] 
+                    [pre-used integer?] 
+                    [pre-admin integer?] 
+                    [code-page-total integer?] 
+                    [post-used integer?] 
+                    [post-admin integer?] 
+                    [start-time integer?] 
+                    [end-time integer?] 
+                    [start-real-time real?] 
+                    [end-real-time real?]) 
+                   #:prefab]{
+  Represents a garbage collection.  The only fields used by the visualizer 
+  are @racket[start-real-time] and @racket[end-real-time], which are inexact 
+  numbers representing time in the same way as @racket[current-inexact-milliseconds].
+}

collects/scribblings/reference/concurrency.scrbl

@@ -17,8 +17,6 @@ support for parallelism to improve performance.
 @include-section["sync.scrbl"]
 @include-section["thread-local.scrbl"]
 @include-section["futures.scrbl"]
-@include-section["futures-visualizer.scrbl"]
-@include-section["futures-trace.scrbl"]
 @include-section["places.scrbl"]
 @include-section["distributed.scrbl"]
 @include-section["engine.scrbl"]

collects/scribblings/reference/futures-logging.scrbl

@@ -1,98 +1,7 @@
 #lang scribble/doc 
 @(require "mz.rkt" (for-label racket/future future-visualizer/trace)) 
 
-@title[#:tag "futures-trace"]{Futures Tracing} 
+@title[#:tag "future-logging"]{Future Performance Logging}
-
-@guideintro["effective-futures"]{the future visualizer}
-
-@defmodule[future-visualizer/trace]
-
-The @deftech{futures trace} module exposes low-level information about 
-the execution of parallel programs written using @racket[future].   
-  
-@deftogether[(
-  @defform[(trace-futures e ...)] 
-  @defproc[(trace-futures-thunk [thunk (-> any)]) (listof indexed-future-event?)]
-)]{
- The @racket[trace-futures] macro and @racket[trace-futures-thunk] function 
- track the execution of a program using futures and return the program 
- trace as a list of @racket[indexed-future-event] structures.
- 
- This program:
- 
- @racketblock[ 
-    (require racket/future 
-             future-visualizer/trace) 
-     
-    (trace-futures  
-     (let ([f (future (lambda () ...))]) 
-       ... 
-       (touch f)))
- ]
- 
- Is equivalent to:
- 
- @racketblock[ 
-    (require racket/future 
-             future-visualizer/trace) 
-                                      
-    (start-future-tracing!) 
-    (let ([f (future (lambda () ...))]) 
-      ... 
-      (touch f)) 
-    (stop-future-tracing!)
-    (timeline-events)
- ]
-}
-
-@deftogether[(
-  @defproc[(start-future-tracing!) void?]
-  @defproc[(stop-future-tracing!) void?]
-  @defproc[(timeline-events) (listof indexed-future-event?)]
-)]{
- The @racket[start-future-tracing!] procedure enables the collection 
- of future-related execution data.  This function should be called immediately 
- prior to executing code the programmer wishes to profile. 
- 
- The @racket[stop-future-tracing!] procedure must be used to indicate the 
- end of code the programmer wishes to trace.  Tracing works by simply using a 
- log receiver to record all future-related log events; this procedure logs a 
- special message that is well-known to the log receiver to mean 'stop recording'.
- 
- The @racket[timeline-events] procedure returns the program trace as 
- a list of @racket[indexed-future-event] structures. 
-}
-  
-@defstruct[indexed-future-event ([index exact-nonnegative-integer?] 
-                                 [event (or future-event? gc-info?)])]{
-  Represents an individual log message in a program trace.  In addition to 
-  future events, the tracing code also records garbage collection events; hence 
-  the @racket[event] field may contain either a @racket[future-event] or @racket[gc-info], 
-  where the latter describes a GC operation.  Because multiple 
-  @racket[future-event] structures may contain identical timestamps, the 
-  @racket[index] field ranks them in the order in which they were recorded 
-  in the log output.
-}
-                                                                      
-@defstruct[gc-info ([major? boolean?] 
-                    [pre-used integer?] 
-                    [pre-admin integer?] 
-                    [code-page-total integer?] 
-                    [post-used integer?] 
-                    [post-admin integer?] 
-                    [start-time integer?] 
-                    [end-time integer?] 
-                    [start-real-time real?] 
-                    [end-real-time real?]) 
-                   #:prefab]{
-  Represents a garbage collection.  The only fields used by the visualizer 
-  are @racket[start-real-time] and @racket[end-real-time], which are inexact 
-  numbers representing time in the same way as @racket[current-inexact-milliseconds].
-}
-
-@; ------------------------------------------------------------
-
-@section[#:tag "future-logging"]{Future Performance Logging}
 
 Racket traces use logging (see @secref["logging"]) extensively to
 report information about how futures are evaluated.  Logging output is
@@ -108,13 +17,10 @@ In addition to its string message, each event logged for a future has
 a data value that is an instance of a @racket[future-event]
 @tech{prefab} structure:
 
-@defstruct[future-event ([future-id (or exact-nonnegative-integer? #f)]
+@racketblock[
-                         [proc-id exact-nonnegative-integer?] 
+(define-struct future-event (future-id proc-id action time)
-                         [action symbol?] 
+  #:prefab)
-                         [time-id real?] 
+]
-                         [prim-name (or symbol? #f)] 
-                         [user-data (or #f symbol? exact-nonnegative-integer?)]) 
-                        #:prefab]
 
 The @racket[future-id] field is an exact integer that identifies a
 future, or it is @racket[#f] when @racket[action] is
@@ -229,5 +135,3 @@ values depending on both the @racket[action] and @racket[prim-name] fields:
         of the newly created future.}
                                      
  ]
-
-@; ----------------------------------------------------------------------                                                       

collects/scribblings/reference/futures.scrbl

@@ -48,6 +48,8 @@ A future never runs in parallel if all of the @tech{custodians} that
 allow its creating thread to run are shut down. Such futures can
 execute through a call to @racket[touch], however.
 
+@section{Creating and Touching Futures}
+
 @deftogether[(
   @defproc[(future [thunk (-> any)]) future?]
   @defproc[(touch [f future?]) any]
@@ -124,6 +126,10 @@ execute through a call to @racket[touch], however.
 
 }
 
+@; ----------------------------------------
+
+@section{Future Semaphores}
+
 @defproc[(make-fsemaphore [init exact-nonnegative-integer?]) fsemaphore?]{
 
   Creates and returns a new @deftech{future semaphore} with the
@@ -175,4 +181,8 @@ execute through a call to @racket[touch], however.
 
 }
 
+@; ----------------------------------------
+
+@include-section["futures-logging.scrbl"]
+
 @close-eval[future-eval]