Rakka: Actor Model for Racket🔗ℹ

1.1 Proof of Life🔗ℹ

Run an actor in 3 lines:

#lang rakka

(require rakka)

(spawn (lambda () (displayln "I'm an actor!")))

You just ran an isolated process. Now let’s build something useful.

1.2 Your First GenServer🔗ℹ

One-shot actors aren’t practical. For stateful services, use GenServer:

#lang racket/base

(require rakka racket/match)

(struct counter ()

#:methods gen:server

[(define (init self args)

(ok 0))  ; start at 0

(define (handle-call self msg state from)

(match msg

['get (reply state state)]

['inc (reply 'ok (add1 state))]))

(define (handle-cast self msg state)

(noreply state))

(define (handle-info self msg state)

(noreply state))

(define (terminate self reason state)

(void))])

;; Use it

(define c (gen-server-start (counter) #f))

(gen-server-call c 'inc)  ; => 'ok

(gen-server-call c 'inc)  ; => 'ok

(gen-server-call c 'get)  ; => 2

(gen-server-stop c)

2.1 The Callbacks🔗ℹ

You implement these, Rakka calls them:

2.2 Calls vs Casts🔗ℹ

Calls are synchronous—the caller blocks until you reply:

;; Client side

(gen-server-call my-server 'get-data)  ; blocks

;; Server side (handle-call)

(reply the-data new-state)  ; unblocks the caller

Casts are asynchronous—fire and forget:

;; Client side

(gen-server-cast! my-server 'reset)  ; returns immediately

;; Server side (handle-cast)

(noreply new-state)  ; no reply expected

Use calls when you need a response. Use casts when you don’t.

2.3 The handle-info Callback🔗ℹ

5.1 Links: Shared Fate🔗ℹ

Linked processes die together. If one crashes, the other gets an exit signal:

;; Link when starting

(gen-server-start-link (my-server) args)

;; Or link explicitly

(link! some-pid)

By default, exit signals kill the receiver. To catch them instead:

(set-trap-exit! (self) #t)

;; Now exits arrive in handle-info

(define (handle-info self msg state)

(match msg

[(exit-signal from reason)

(printf "~a died: ~a\n" from reason)

(noreply state)]

[_ (noreply state)]))

5.2 Monitors: One-Way Watching🔗ℹ

Monitors let you watch without shared fate. If the target dies, you get notified but don’t die:

(define ref (monitor! some-pid))

;; In handle-info:

(match msg

[(down-signal ref pid reason)

(printf "~a died: ~a\n" pid reason)

(noreply state)])

Use demonitor! to stop watching.

5.3 When to Use Which🔗ℹ

6.1 Basic Supervision🔗ℹ

(define sup-pid

(supervisor-start-link

'one-for-one    ; restart strategy

3               ; max 3 restarts

5               ; in 5 seconds

(list

(child-spec* #:id 'cache

#:start (lambda () (gen-server-start-link (kv-store) #f))

#:restart 'permanent)

(child-spec* #:id 'worker

#:start (lambda () (gen-server-start-link (worker) #f))

#:restart 'permanent))))

If a child crashes, the supervisor restarts it. If it crashes too often (3 times in 5 seconds), the supervisor gives up and terminates.

6.2 Restart Strategies🔗ℹ

6.3 Restart Types🔗ℹ

6.4 Child Specs🔗ℹ

(child-spec* #:id 'my-worker           ; unique identifier

#:start start-fn          ; (-> pid?) returns linked pid

#:restart 'permanent      ; restart policy

#:shutdown 5000)          ; ms to wait for graceful stop

8.1 Spawn and Messages🔗ℹ

;; Spawn a process

(define pid (spawn (lambda ()

(displayln "Started!")

(define msg (receive))  ; block for message

(printf "Got: ~a\n" msg))))

;; Send it a message

(send! pid 'hello)

8.2 The Actor Loop Pattern🔗ℹ

Raw actors typically loop, handling messages:

(define (counter-actor initial)

(let loop ([count initial])

(match (receive)

['inc (loop (add1 count))]

[(list 'get from)

(send! from count)

(loop count)]

['stop (void)])))

8.3 When to Use Raw Actors🔗ℹ

For application code, use GenServer.

9.1 Cooperative vs Preemptive🔗ℹ

Green threads yield at receive points. But what if an actor computes without receiving? It starves other actors.

Solution: Use #lang rakka for fair scheduling.

#lang rakka  ; <-- enables preemptive yielding

(require rakka)

(define (fib n)

(if (<= n 1) n

(+ (fib (- n 1)) (fib (- n 2)))))

;; Even fib(30) won't starve other actors

(spawn (lambda () (printf "fib(30) = ~a\n" (fib 30))))

(spawn (lambda () (displayln "I run too!")))

#lang rakka counts function calls and yields after ~4000, like Erlang’s reduction counting.

9.2 Threaded Mode🔗ℹ

For CPU-bound parallelism, switch to OS threads:

(runtime-mode 'threaded)

(spawn (lambda ()

;; This runs on a real OS thread

(heavy-computation)))

9.3 Performance Comparison🔗ℹ

Use green mode unless you need CPU parallelism.

11.1 Starting Nodes🔗ℹ

;; Start EPMD (once per machine)

(define epmd (start-epmd! 4369))

;; Start this node

(start-node! "mynode@localhost" 9001

#:cookie "secret-cookie")

The cookie must match between nodes.

11.2 Connecting and Messaging🔗ℹ

;; On node2

(start-node! "node2@localhost" 9002

#:cookie "secret-cookie")

(connect-node! "mynode@localhost")

;; Send to a globally registered process

(global-send! 'calculator '(add 1 2))

11.3 Global Registry🔗ℹ

;; Register globally (visible on all nodes)

(global-register! 'calculator my-pid)

;; Look up from any node

(define calc (global-whereis 'calculator))

11.4 Remote Spawning🔗ℹ

;; On remote node, register a spawn handler

(register-spawn-handler! 'my-worker

(lambda (args) (spawn (lambda () (worker-loop args)))))

;; From any node, spawn remotely

(define remote-pid

(request-spawn! "node2@localhost" 'my-worker '(args)))

12.1 Basic Reload🔗ℹ

(hot-reload! "my-server.rkt")

12.2 State Migration🔗ℹ

When code changes, the code-change callback transforms old state to new:

(struct my-server ()

#:methods gen:server

[;; ... other callbacks ...

(define (code-change self version-info state)

(match (version-info-new-version version-info)

["2.0"

;; Migrate state from v1 to v2

(ok (upgrade-state state))]

[_ (ok state)]))])

;; Trigger the upgrade

(trigger-code-change! pid (version-info "1.0" "2.0" #f))

12.3 Tree-Wide Upgrades🔗ℹ

Upgrade an entire supervision tree (children first, then supervisor):

(upgrade-supervisor-tree! sup-pid (version-info "1.0" "2.0" #f))

13.1 Logging🔗ℹ

(current-rakka-log-level 'debug)

(set-process-log-level! some-pid 'error)

(rakka-log-info "Starting on port ~a" port)

(rakka-log-error "Connection failed: ~a" reason)

Lifecycle events (SPAWN, EXIT, CRASH, RESTART) are logged automatically.

13.2 Metrics🔗ℹ

;; Built-in metrics

(counter-value metrics-process-spawns)

(gauge-value metrics-active-processes)

;; Custom metrics

(define reqs (make-counter 'http-requests))

(counter-inc! reqs)

(define conns (make-gauge 'connections))

(gauge-inc! conns)

(gauge-dec! conns)

13.3 Process Introspection🔗ℹ

(sys-get-state some-pid)   ; get current state

(sys-suspend some-pid)     ; pause processing

(sys-resume some-pid)      ; resume

(sys-trace some-pid #t)    ; enable tracing

13.4 Graceful Shutdown🔗ℹ

(on-shutdown

(lambda (ctx) (close-connections))

#:priority 10

#:name 'cleanup)

(graceful-shutdown #:timeout 30000)

16.1 Your First Table🔗ℹ

#lang racket/base

(require rakka)

;; Create a table (must be inside an actor)

(spawn (lambda ()

(define cache (table-new 'my-cache #:type 'set))

(table-insert! cache 'user-123 '((name . "Alice") (score . 42)))

(table-lookup cache 'user-123)  ; => '((name . "Alice") (score . 42))

(table-update! cache 'user-123

(lambda (user) (cons '(vip . #t) user))

'())

(displayln (table-lookup cache 'user-123))))

That’s it. You have isolated shared state.

16.2 Why Tables Exist🔗ℹ