Jobsched: Running jobs with multiple Racket instances🔗ℹ

1 Remote-Call: Remote function calls🔗ℹ

The jobsched/remote-call module provides a higher-level interface where jobs are expressed as function calls.

"server-worker-remote-call.rkt"

#lang racket

(require jobsched)

;; Functions used by the server must be `provide`d.

(provide greet total)

(define (greet name #:greeting [greeting "Hello"])

(format "~a, ~a!" greeting name))

(define (total prices #:tax-rate [tax-rate 0])

(define subtotal (apply + prices))

(exact->inexact (* subtotal (+ 1 tax-rate))))

;;=== Worker ===;;

;; The worker resolves and calls the functions automatically.

(module+ worker (start-remote-call-worker))

;;=== Server ===;;

(module+ main

(start-simple-server

#:worker-file (this-file)

;; These look like function calls, but they are captured and

;; sent to the workers for execution. Arguments are evaluated

;; here; the function itself is resolved on the worker.

#:data-list (list (remote-call (greet "Alice"))

(remote-call (greet "Bob" #:greeting "Hi"))

(remote-call (total '(10 20 30)))

(remote-call (total '(100 200) #:tax-rate 0.2)))

#:process-result (λ (data result) (displayln result))

#:n-workers 3))

The worker then uses dynamic-require to resolve the function and applies it with the captured arguments. This means the server and worker are guaranteed to call the same function—eliminating the risk of module path mismatches.

Important: The arguments to the function are evaluated on the server before being serialized and sent to the worker. The worker receives only the function name and the serialized argument values, and calls the function on these values. In particular, procedures and closures are not serializable (via racket/fasl) and cannot be passed as arguments. Only the top-level function itself is resolved on the worker via dynamic-require.

Remark: In the example above, the functions, the worker and the server are all defined in the same file. This is not a requirement, and they can be in three different files.

We recommend requiring define2 in the module where the functions are defined, so as to raise compile-time errors about the function’s signature.

At run time, the arguments are evaluated and stored in the job data, but the function is not called—it will be called on the worker.

The data argument received by the #:process-result callback is the remote-call value. You can inspect it with the following accessors and predicate:

For each received job, the worker uses dynamic-require to load the function from the embedded module path, then calls it with the stored arguments.

2 Lower-level API🔗ℹ

The following sections document the lower-level server/worker API for cases where remote-call does not provide enough control—for example, when the worker needs to perform custom setup, or when job data is not a function call.

All definitions exported by the various modules below are also exported by jobsched.

3 Simple server / worker🔗ℹ

Note that start-simple-worker can be used with start-simple-server, server-start and scheduler-start.

IMPORTANT: See the remarks for start-worker.

The workers will receive one element of data-list at a time, and return a result to be processed by process-result.

The server starts n-workers workers in separate OS processes. Refer to scheduler-start for close-workers?.

Note: By contrast to scheduler-start, the simple server does not allow to add more tasks while it is running.

start-simple-server is essentially a combination of make-server, server-start and server-close.

"server-worker-simple.rkt"

#lang racket

(require jobsched)

;=== Worker ===;

(define (worker-run data)

(match data

[(list x y)

(* x y)]))

(module+ worker

(start-simple-worker worker-run))

;=== Server ===;

(module+ main

(define (process-result data result)

(printf "~a × ~a = ~a\n" (first data) (second data) result))

(define data-list

(for*/list ([x 5] [y 5]) (list x y)))

(start-simple-server

#:worker-file (this-file)

#:data-list data-list

#:process-result process-result))

4 Server🔗ℹ

5 Job🔗ℹ

The cost field is used by the priority queue of the server.

The data field contains readable? (in the sense of racket/fasl) information that is sent to the worker for processing.

The fields start-ms and stop-ms are set automatically by the server when a job is sent to a worker and when the result is received.

6 Server🔗ℹ

See also make-racket-cmd.

The data will be sent to the worker, who will receive it on its input port and will be accessible via job-data.

The cost is used for ordering the job in the priority queue, which is ordered by minimum cost.

If close-workers? is not #f, then all worker instances are closed when returning from the function call, and the workers normally terminate gracefully. If close-workers? is #f, workers are not closed when returning from the call, so they can be re-used for a subsequent call to scheduler-start without starting the workers (and the corresponding racket instances) again. If n-workers is #f, the number of running worker instances is not changed, and previous running instances are re-used. If there are already more running worker instances than n-workers, some workers are killed to match n-workers.

The callback before-start is called before a job is sent to a worker. The callback after-stop is called when a job is finished and the result is received from the worker. Both callbacks can be used to add new jobs to the queue, using scheduler-add-job!.

See an example of using scheduler-start in examples/server-worker.

7 Worker🔗ℹ

See example at the top.

Communication between server and worker uses TCP on localhost. The worker’s stdout/stderr are redirected to the server’s stderr, so printf and displayln calls in the worker are visible for debugging and do not interfere with the protocol.

run-job must return a readable? value (in the sense of racket/fasl), and (void) is not readable.

8 Utilities🔗ℹ

9 Comparison with other Racket parallelism mechanisms🔗ℹ

Futures can make use of many cores and can share memory, but are limited in the kind of operations they can handle without blocking. Futures are well suited for numerical applications where garbage collection can be greatly reduced, allowing to make the most of the CPUs without requiring multiple Racket instances.

Places allow more free-form racket computation and can make use of multiple cores and can share memory, but are still constrained by a single garbage collector, which prevents from making full use of all the cores.

Distributed Places create separate Racket instances like jobsched but can also spawn workers on remote machines. When all workers are on the same machine, jobsched may be simpler to use.