On this page:
trace-futures
trace-futures-thunk
start-future-tracing!
stop-future-tracing!
timeline-events
indexed-future-event
future-event
gc-info

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

(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.