3 Futures Tracing

(require future-visualizer/trace)
	package: future-visualizer-pict

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 : any

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 prefab struct (see Garbage Collection), 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.