3 Futures Tracing

top← prev up next →

3 Futures Tracing

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
(start-future-tracing!) → void?
procedure
(stop-future-tracing!) → void?
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.

top← prev up next →