► |  | The Racket Reference

1 | Language Model
2 | Syntactic Forms
3 | Datatypes
4 | Structures
5 | Classes and Objects
6 | Units
7 | Contracts
8 | Pattern Matching
9 | Control Flow
10 | Concurrency and Parallelism
11 | Macros
12 | Input and Output
13 | Reflection and Security
14 | Operating System
15 | Memory Management
16 | Unsafe Operations
17 | Running Racket
| Bibliography
| Index

▼ | 10 | Concurrency and Parallelism

10.1 | Threads
10.2 | Synchronization
10.3 | Thread-Local Storage
10.4 | Futures
10.5 | Futures Visualizer
10.6 | Futures Tracing
10.7 | Places
10.8 | Distributed Places

► | 10.5 | Futures Visualizer

10.5.1 | Execution Timeline
10.5.2 | Future Creation Tree

On this page:

visualize-futures
visualize-futures-thunk
show-visualizer
10.5.1`` Execution Timeline
timeline-pict
10.5.2`` Future Creation Tree
creation-tree-pict

top← prev up next →

#### 10.5`` Futures Visualizer

> > > Parallelism with Futures in The Racket Guide introduces the future visualizer.

(require future-visualizer)

The futures visualizer is a graphical profiling tool for parallel programs written using future. The tool shows a timeline of a program’s execution including all future-related events, as well as the overall amount of processor utilization at any point during the program’s lifetime.

> syntax (visualize-futures e ...)
> procedure (visualize-futures-thunk thunk) → any
> thunk : (-> any)

The visualize-futures macro enables the collection of data required by the visualizer and displays a profiler window showing the corresponding trace. The visualize-futures-thunk provides similar functionality where program code is contained within thunk.

A typical program using profiling might look like the following:

> (require racket/future
> future-visualizer)
> (visualize-futures
> (let ([f (future (lambda () ...))])
> ...
> (touch f)))

The preceding program is equivalent to:

> (require racket/future
> future-visualizer/trace
> future-visualizer)
> (start-future-tracing!)
> (let ([f (future (lambda () ...))])
> ...
> (touch f))
> (stop-future-tracing!)
> (show-visualizer)

> procedure (show-visualizer #:timeline timeline) → void?
> timeline : (listof indexed-future-event?)

Displays the visualizer window. If the function is called with no arguments, it must be preceded by the following sequence: a call to start-future-tracing!, program code that is being traced, and a call to stop-future-tracing! – in which case the visualizer will show data for all events logged in between those calls (via timeline-events). Note that visualize-futures and visualize-futures-thunk are simpler alternatives to using these primitives directly. The timeline argument can be used to show the visualizer for a previously-generated trace.

##### 10.5.1`` Execution Timeline

The execution timeline, shown in the top left-hand corner of the profiler window, displays a history of the program and all events associated with its futures, with OS-level threads or processes organized along the y-axis and time increasing along the x-axis. A coloring convention is used to distinguish between different types of events (see Future Performance Logging for a full description of these event types):

- Blue dot: 'create

- Green bar: 'start-work, 'start-0-work

- Orange dot: 'sync

- Red dot: 'block, 'touch

- White dot: 'result, 'end-work

- Green dot: 'touch-pause, 'touch-resume

Mousing over any event connects it via purple lines to the sequence of events for its future. Additionally, orange dotted lines with arrowheads may be shown to indicate operations performed from one future to another (e.g. 'create or 'touch actions). To view details about two events simultaneously, a selection can be tacked by clicking the mouse.

The timeline displays vertical lines at 100-microsecond intervals. Note that though the time interval is fixed, the pixel distance between lines varies based on the event density for any given time range to prevent overlapping event circles.

> > procedure
> > (timeline-pict |  | events |
> > | [ | #:x x |
> > |  | #:y y |
> > |  | #:width width |
> > |  | #:height height |
> > |  | #:selected-event-index selected-event-index]) |
> → pict?
> events : (listof indexed-future-event?)
> x : (or #f exact-nonnegative-integer?) = #f
> y : (or #f exact-nonnegative-integer?) = #f
> width : (or #f exact-nonnegative-integer?) = #f
> height : (or #f exact-nonnegative-integer?) = #f
> selected-event-index : (or #f exact-nonnegative-integer?) = #f

Returns a pict showing the execution timeline for the trace in events. The optional arguments x, y, width, and height can be used to obtain a specific area (in pixels) of the timeline image. The selected-event-index argument, if specified, shows the timeline image as if the user placed the mouse pointer over the indexed-future-event with the corresponding index.

##### 10.5.2`` Future Creation Tree

The creation tree shows a tree with a single node per future created by the program. This display can be particularly useful for programs which spawn futures in nested fashion (futures within futures). For any given future node, the children of that node represent futures which were created by that future (within the scope of its thunk). For all programs, the root of the tree is a special node representing the main computation thread (the runtime thread), and is denoted RTT.

> > procedure
> > (creation-tree-pict |  | events |  |  |  |
> > | [ | #:x x |  |  |  |
> > |  | #:y y |  |  |  |
> > |  | #:width width |  |  |  |
> > |  | #:node-width node-width |  |  |  |
> > |  | #:height height |  |  |  |
> > |  | #:padding padding |  |  |  |
> > |  | #:zoom zoom]) |  | → |  | pict?
> events : (listof indexed-future-event?)
> x : (or #f exact-nonnegative-integer?) = #f
> y : (or #f exact-nonnegative-integer?) = #f
> width : (or #f exact-nonnegative-integer?) = #f
> node-width : (or #f exact-nonnegative-integer?) = #f
> height : (or #f exact-nonnegative-integer?) = #f
> padding : (or #f exact-nonnegative-integer?) = #f
> zoom : exact-nonnegative-integer? = 1

Returns a pict showing the future creation tree for the trace in events. The optional arguments x, y, width, and height can be used to obtain a specific area (in pixels) of the creation tree image. The node-width argument specifies (in pixels) the diameter of each node. The padding argument specifies the minimum space vertically between each depth and horizontally between siblings. The zoom argument specifies the zoom factor for the tree image in the range 1-5, where 5 returns a 500% zoom.
top← prev up next →