3 Futures Tracing

▼ |  | Futures Visualizer

1 | Execution Timeline
2 | Future Creation Tree
3 | Futures Tracing

On this page:

trace-futures
trace-futures-thunk
start-future-tracing!
stop-future-tracing!
timeline-events
indexed-future-event
future-event

top ← prev up next →

### 3`` Futures Tracing

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

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.
top ← prev up next →