diff --git a/collects/future-visualizer/info.rkt b/collects/future-visualizer/info.rkt new file mode 100644 index 0000000000..14aae45b14 --- /dev/null +++ b/collects/future-visualizer/info.rkt @@ -0,0 +1,4 @@ +#lang setup/infotab + +(define scribblings + '(("scribblings/future-visualizer.scrbl" (multi-page) (tool)))) diff --git a/collects/future-visualizer/scribblings/common.rkt b/collects/future-visualizer/scribblings/common.rkt new file mode 100644 index 0000000000..e445f288ea --- /dev/null +++ b/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 "))))) diff --git a/collects/scribblings/reference/futures-visualizer.scrbl b/collects/future-visualizer/scribblings/future-visualizer.scrbl similarity index 95% rename from collects/scribblings/reference/futures-visualizer.scrbl rename to collects/future-visualizer/scribblings/future-visualizer.scrbl index 70593c4098..026b3bfa97 100644 --- a/collects/scribblings/reference/futures-visualizer.scrbl +++ b/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"] diff --git a/collects/future-visualizer/scribblings/futures-trace.scrbl b/collects/future-visualizer/scribblings/futures-trace.scrbl new file mode 100644 index 0000000000..b934d98782 --- /dev/null +++ b/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]. +} diff --git a/collects/scribblings/reference/concurrency.scrbl b/collects/scribblings/reference/concurrency.scrbl index 3dc3bca9fa..2d7f08e211 100644 --- a/collects/scribblings/reference/concurrency.scrbl +++ b/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"] diff --git a/collects/scribblings/reference/futures-trace.scrbl b/collects/scribblings/reference/futures-logging.scrbl similarity index 59% rename from collects/scribblings/reference/futures-trace.scrbl rename to collects/scribblings/reference/futures-logging.scrbl index c81f02e8ed..e537ffcf50 100644 --- a/collects/scribblings/reference/futures-trace.scrbl +++ b/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} - -@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} +@title[#: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)] - [proc-id exact-nonnegative-integer?] - [action symbol?] - [time-id real?] - [prim-name (or symbol? #f)] - [user-data (or #f symbol? exact-nonnegative-integer?)]) - #:prefab] +@racketblock[ +(define-struct future-event (future-id proc-id action time) + #: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.} ] - -@; ---------------------------------------------------------------------- \ No newline at end of file diff --git a/collects/scribblings/reference/futures.scrbl b/collects/scribblings/reference/futures.scrbl index dd7802e5d2..b334c6c9e7 100644 --- a/collects/scribblings/reference/futures.scrbl +++ b/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]