3 Futures Tracing
(require future-visualizer/trace) |
The futures trace module exposes low-level information about the execution of parallel programs written using future.
syntax
(trace-futures e ...)
procedure
(trace-futures-thunk thunk) → (listof indexed-future-event?)
thunk : (-> any)
The trace-futures macro and trace-futures-thunk function
track the execution of a program using futures and return the program
trace as a list of indexed-future-event structures.
This program:
(require racket/future future-visualizer/trace) (trace-futures (let ([f (future (lambda () ...))]) ... (touch f)))
Is equivalent to:
(require racket/future future-visualizer/trace) (start-future-tracing!) (let ([f (future (lambda () ...))]) ... (touch f)) (stop-future-tracing!) (timeline-events)
procedure
procedure
procedure
(timeline-events) → (listof indexed-future-event?)
The 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 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 timeline-events procedure returns the program trace as a list of indexed-future-event structures.
struct
(struct indexed-future-event (index event) #:extra-constructor-name make-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 event field may contain either a future-event or gc-info,
where the latter describes a GC operation. Because multiple
future-event structures may contain identical timestamps, the
index field ranks them in the order in which they were recorded
in the log output.
struct
(struct future-event ( future-id proc-id action time-id prim-name user-data) #:extra-constructor-name make-future-event #:prefab) 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?)
Represents a future event as logged by the run-time system. See
Future Performance Logging for more information.
struct
(struct gc-info ( major? pre-used pre-admin code-page-total post-used post-admin start-time end-time start-real-time end-real-time) #:extra-constructor-name make-gc-info #:prefab) 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?
Represents a garbage collection. The only fields used by the visualizer
are start-real-time and end-real-time, which are inexact
numbers representing time in the same way as current-inexact-milliseconds.