▼ |  | 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
gc-info

top ← prev up next →

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