On this page:
place?
place-channel?
place
place-wait
place-channel
place-channel-send
place-channel-receive
place-channel-send/ receive

10.5 Places

Parallel support for place is currently disabled by default. Enable places by supplying --enable-places to configure when building Racket.

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

Places enable the development of parallel programs that take advantage of machines with multiple processors, cores, or hardware threads.

A place is a parallel task that is effectively a separate instance of the Racket virtual machine. Places communicate through place channels, which are endpoints for a two-way buffered communication.

To a first approximation, place channels allow only immutable values as messages over the channel: numbers, characters, booleans, immutable pairs, immutable vectors, and immutable structures. In addition, place channels themselves can be sent across channels to establish new (possibly more direct) lines of communication in addition to any existing lines. Finally, mutable values produced by shared-flvector, make-shared-flvector, shared-fxvector, make-shared-fxvector, shared-bytes, and make-shared-bytes can be sent across place channels; mutation of such values is visible to all places that share the value, because they are allowed in a shared memory space.

A place channel can be used as a synchronizable event (see Events) to receive a value through the channel. A place can also receive messages with place-channel-receive, and messages can be sent with place-channel-send.

Constraints on messages across a place channel—and therefore on the kinds of data that places share—enable greater parallelism than future, even including separate garbage collection of separate places. At the same time, the setup and communication costs for places can be higher than for futures.

For example, the following expression lanches two places, echoes a message to each, and then waits for the places to complete and return:

(let ([pls (for/list ([i (in-range 2)])
              (place "place-worker.rkt" 'place-main))])
   (for ([i (in-range 2)]
         [p pls])
      (place-channel-send p i)
      (printf "~a\n" (place-channel-receive p)))
   (map place-wait pls))

The "place-worker.rkt" module must export the place-main function that each place executes, where place-main must accept a single place channel argument:

#lang racket
(provide place-main)
 
(define (place-main pch)
  (place-channel-send pch (format "Hello from place ~a"
                                  (place-channel-receive pch))))

(place? v)  boolean?
  v : any/c
Returns #t if v is a place descriptor value, #f otherwise. Every place descriptor is also a place channel.

(place-channel? v)  boolean?
  v : any/c
Returns #t if v is place channel, #f otherwise.

(place module-path start-proc)  place?
  module-path : module-path?
  start-proc : symbol?
Creates a place to run the procedure that is identified by module-path and start-proc. The result is a place descriptor value that represents the new parallel task; the place descriptor is returned immediately. The place descriptor value is also a place channel that permits communication with the place.

The module indicated by module-path must export a function with the name start-proc. The function must accept a single argument, which is a place channel that corresponds to the other end of communication for the place descriptor returned by place.

(place-wait p)  exact-integer?
  p : place?
Returns the completion value of the place indicated by p, blocking until the place completes if it has not already completed.

Returns two place channels. Data sent through the first channel can be received through the second channel, and data sent through the second channel can be received from the first.

Typically, one place channel is used by the current place to send messages to a destination place; the other place channel is sent to the destination place (via an existing place channel).

(place-channel-send pch v)  void
  pch : place-channel?
  v : any/c
Sends an immutable message v on channel pch.

Returns an immutable message received on channel pch.

(place-channel-send/receive pch v)  void
  pch : place-channel?
  v : any/c
Sends an immutable message v on channel pch and then waits for a reply message on the same channel.