On this page:
10.4.1 Future Performance Logging

10.4 Futures

+Parallelism with Futures in The Racket Guide introduces futures.

The bindings documented in this section are provided by the racket/future and racket libraries, but not racket/base.

Currently, parallel support for future is enabled by default for Windows, Linux x86/x86_64, and Mac OS X x86/x86_64. To enable support for other platforms, use --enable-futures with configure when building Racket.

The future and touch functions from racket/future provide access to parallelism as supported by the hardware and operating system. In contrast to thread, which provides concurrency for arbitrary computations without parallelism, future provides parallelism for limited computations. A future executes its work in parallel (assuming that support for parallelism is available) until it detects an attempt to perform an operation that is too complex for the system to run safely in parallel. Similarly, work in a future is suspended if it depends in some way on the current continuation, such as raising an exception. A suspended computation for a future is resumed when touch is applied to the future.

“Safe” parallel execution of a future means that all operations provided by the system must be able to enforce contracts and produce results as documented. “Safe” does not preclude concurrent access to mutable data that is visible in the program. For example, a computation in a future might use set! to modify a shared variable, in which case concurrent assignment to the variable can be visible in other futures and threads. Furthermore, guarantees about the visibility of effects and ordering are determined by the operating system and hardware—which rarely support, for example, the guarantee of sequential consistency that is provided for thread-based concurrency. At the same time, operations that seem obviously safe may have a complex enough implementation internally that they cannot run in parallel. See also Parallelism with Futures in The Racket Guide.

A future never runs in parallel if all of the custodians that allow its creating thread to run are shut down. Such futures can execute through a call to touch, however.

(future thunk)  future?
  thunk : (-> any)
(touch f)  any
  f : future?
The future procedure returns a future value that encapsulates thunk. The touch function forces the evaluation of the thunk inside the given future, returning the values produced by thunk. After touch forces the evaluation of a thunk, the resulting values are retained by the future in place of thunk, and additional touches of the future return those values.

Between a call to future and touch for a given future, the given thunk may run speculatively in parallel to other computations, as described above.

> (let ([f (future (lambda () (+ 1 2)))])
    (list (+ 3 4) (touch f)))

'(7 3)

(current-future)  (or/c #f future?)
Returns the descriptor of the future whose thunk execution is the current continuation. If a future thunk itself uses touch, future-thunk executions can be nested, in which case the descriptor of the most immediately executing future is returned. If the current continuation is not a future-thunk execution, the result is #f.

(future? v)  boolean?
  v : any/c
Returns #t if v is a future value, #f otherwise.

Returns the number of parallel computation units (e.g., processors or cores) that are available on the current machine.

Creates and returns a new future semaphore with the counter initially set to init.

A future semaphore is similar to a plain semaphore, but future-semaphore operations can be performed safely in parallel (to synchronize parallel computations). In contrast, operations on plain semaphores are not safe to perform in parallel, and they therefore prevent a computation from continuing in parallel.

(fsemaphore? v)  boolean?
  v : any/c
Returns #t if v is an future semaphore value, #f otherwise.

(fsemaphore-post fsema)  void?
  fsema : fsemaphore?
Increments the future semaphore’s internal counter and returns #<void>.

(fsemaphore-wait fsema)  void?
  fsema : fsemaphore?
Blocks until the internal counter for fsema is non-zero. When the counter is non-zero, it is decremented and fsemaphore-wait returns #<void>.

(fsemaphore-try-wait? fsema)  boolean?
  fsema : fsemaphore?
Like fsemaphore-wait, but fsemaphore-try-wait? never blocks execution. If fsema’s internal counter is zero, fsemaphore-try-wait? returns #f immediately without decrementing the counter. If fsema’s counter is positive, it is decremented and #t is returned.

Returns fsema’s current internal counter value.

10.4.1 Future Performance Logging

Racket futures use logging (see Logging) extensively to report information about how futures are evaluated. Logging output is useful for debugging the performance of programs that use futures.

In addition to its string message, each event logged for a future has a data value that is an instance of a future-event prefab structure:

(define-struct future-event (future-id proc-id action time)

The future-id field is an exact integer that identifies a future, or it is #f when action is 'missing. The future-id field is particularly useful for correlating logged events.

The proc-id fields is an exact, non-negative integer that identifies a parallel process. Process 0 is the main Racket process, where all expressions other than future thunks evaluate.

The time field is an inexact number that represents time in the same way as current-inexact-milliseconds.

The action field is a symbol:

Assuming no 'missing events, then 'start-work or 'start-0-work is always paired with 'end-work, 'sync, 'block, and 'touch are always paired with 'result, 'abort, or 'suspend, and 'touch-pause is always paired with 'touch-resume.

In process 0, some event pairs can be nested within other event pairs: 'sync, 'block, or 'touch with 'result or 'abort, and 'touch-pause with 'touch-resume.}