move future-visualizer docs out of the Reference
This commit is contained in:
Matthew Flatt
parent
d92b9cb404
commit
a774cc93b9
4
collects/future-visualizer/info.rkt
Normal file
4
collects/future-visualizer/info.rkt
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
#lang setup/infotab
|
||||
|
||||
(define scribblings
|
||||
'(("scribblings/future-visualizer.scrbl" (multi-page) (tool))))
|
||||
23
collects/future-visualizer/scribblings/common.rkt
Normal file
23
collects/future-visualizer/scribblings/common.rkt
Normal file
|
|
@ -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 ")))))
|
||||
|
|
@ -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"]
|
||||
100
collects/future-visualizer/scribblings/futures-trace.scrbl
Normal file
100
collects/future-visualizer/scribblings/futures-trace.scrbl
Normal file
|
|
@ -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].
|
||||
}
|
||||
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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.}
|
||||
|
||||
]
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
|
@ -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]
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user