Add spawn/join concurrency extension to Bril #416

ananyagoenka · 2025-05-13T21:45:15Z

This PR implements a lightweight thread‐based concurrency extension for Bril (closes #499).

Highlights

Specification
- docs/extensions/concurrency.md: describes the new thread type, spawn (value‐op) and join (effect‐op), JSON syntax, and well‐formedness rules.
- docs/syntax.md: updated to list spawn and join, and the thread primitive.
Parser Updates
- tools/text/briltxt.py: Lark grammar now recognizes spawn and join.
TypeScript Definitions
- bril-ts/bril.ts:
  - PrimType includes "thread".
  - ValueOpCode adds "spawn", EffectOpCode adds "join".
  - typeCheck and argCounts updated.
- tests/concurrency_types_test.ts: simple deno check smoke test for new ops.
Interpreter Runtime
- src/brili.ts:
  - Introduces ThreadHandle, a global threadTable, and nextTid.
  - Implements spawn (copies args into a fresh Env, launches an async task, returns handle) and join (awaits the associated promise).
  - New --no-workers flag for in-process async mode.
Concurrency Test Suite
- benchmarks/concurrency/:
  - Passing tests (*.bril + *.out) covering correct behavior and errors.
- turnt.toml: adds brili-conc env to run the suite under deno run -A brili.ts.
Micro-benchmarks & Performance
- benchmarks/concurrency/perf/:
  - perf_par_sum_100k.bril, perf_matmul_split.bril, perf_big_par_sum_10M.bril
  - run_perf.sh measures sequential vs concurrent speed-up.
Escape Analysis Pass
- examples/escape.py: intraprocedural pass that reports thread-local allocs.
- tools/README.md: how to run escape.py via bril2json | python3 | deno run.

sampsyo

Awesome; really nice work on this language extension and its implementation here! This is an excellent start.

Aside from some code-level suggestions, I have a few cross-cutting thoughts:

The stuff in benchmarks is (mostly?) better thought of as correctness tests. Benchmarks are more real-ish algorithms. So with the possible exception of the dot product program, let's move these to the test/interp and test/interp-error directories.
A main theme in my comments about the interpreter extension is that it would be possible to avoid some global state, which will keep the interpreter more maintainable/composable. Let me know if this stuff makes sense.

Strategically, I guess I want to suggest that we maybe start by reducing the scope of this PR, get it merged, and defer some extensions to subsequent steps. Would it be possible to trim this PR down to just these things:

the docs
the worker-free sequential fallback implementation in the interpreter
the tests

If we leave out the "real parallelism" implementation and the escape analysis, that should make this PR easy to finalize, and then we can address those things separately. Would that make sense to you, @ananyagoenka?

sampsyo · 2025-05-28T15:57:19Z

bril-ts/bril.ts

-    "store" | "free" |
-    "speculate" | "guard" | "commit";
+  "store" | "free" |
+  "speculate" | "guard" | "commit" | "join";


I'm not sure why the indentation changed here (differences in formatter configuration?), but it would be great to change it back.

sampsyo · 2025-05-28T15:59:15Z

bril-ts/brili_worker.ts

I have generally tried to separate what goes in bril-ts, which is a general-purpose TypeScript library for interacting with Bril programs, from the interpreter that goes in brili.ts. Since this is pretty tightly coupled with the interpreter, I think we probably need to create a separate brili directory where this can live alongside the main source file.

sampsyo · 2025-05-28T16:02:25Z

bril-ts/brili_worker.ts

+  private next = 1;
+  private wait = new Map<number, (v: any) => void>();


I think this machinery could use some comments—it's an interesting approach that involves message-ID-keyed callbacks that is kinda subtle. Maybe a high-level overview of the technique in English could help demystify this a bit?

sampsyo · 2025-05-28T17:15:10Z

bril-ts/brili_worker.ts

+    return new Promise((resolve) => {
+      this.wait.set(id, resolve);
+      // send request back to main thread
+      (self as DedicatedWorkerGlobalScope).postMessage({


Sorry if this is a silly question, but why is it safe to assert self as DedicatedWorkerGlobalScope? I thought that self here would be a HeapProxy, but self is tricky in JavaScript…

sampsyo · 2025-05-28T17:16:06Z

bril-ts/brili_worker.ts

+const sharedHeap = new HeapProxy<any>();
+
+// Message handler
+self.onmessage = async (ev: MessageEvent) => {


I'm a little confused about what self is here—aren't we at the top level of a source file?

sampsyo · 2025-05-28T17:51:42Z

docs/lang/concurrency.md

+* Creates a new thread that begins executing function @func.
+* The caller’s current values of arg1 … argN are copied into the callee’s fresh environment; subsequent changes are not shared.
+* The thread shares the global heap with every other thread in the
+program.
+* Returns a fresh thread handle that uniquely identifies the spawned
+thread.


Let's just make this a plain old paragraph instead of a bulleted list (i.e., please remove the bullets).

sampsyo · 2025-05-28T17:52:16Z

docs/lang/concurrency.md

+  "args":  ["arg1", "arg2", "..."]
+}
+
+* Creates a new thread that begins executing function @func.


Markdown backticks would be helpful here, and in other places where you refer to parts of the instruction:

Suggested change

* Creates a new thread that begins executing function @func.

* Creates a new thread that begins executing function `@func`.

sampsyo · 2025-05-28T17:52:53Z

docs/lang/concurrency.md

+* spawn must provide exactly one function name in funcs.
+* The number of args to spawn must equal the callee’s formal-parameter list.
+* The destination of spawn must be declared with type thread.
+* The sole argument to join must have type thread.


Please move these requirements to the sections that describe each of the relevant instructions.

sampsyo · 2025-05-28T17:53:28Z

docs/lang/concurrency.md

+1
+2
+0


Please mark this as code so it gets laid out correctly.

sampsyo · 2025-05-28T17:54:25Z

docs/lang/concurrency.md

+* Heap allocations created with alloc are global; every thread
+may load or store through any pointer value it holds.
+* If two threads access the same location and at least one access is a
+store, the program has a data race, and the result is undefined.


Maybe it would be nice to link to the SSA and memory extension documentation pages here.

ananyagoenka added 6 commits May 2, 2025 14:27

serial impl working!!

7c136ff

spawn join parse + type checked + interpeted with web workers!!!!!!!

c3f8144

update docs

41a0f4f

now uses shared heap + benchmarks

5240ad9

add more benchmarking and escape analysis

9b4cacc

add perf script

fabdfc8

ananyagoenka mentioned this pull request May 13, 2025

Project Proposal: Concurrency Extension for Bril sampsyo/cs6120#499

Open

sampsyo requested changes May 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add spawn/join concurrency extension to Bril #416

Add spawn/join concurrency extension to Bril #416

Uh oh!

ananyagoenka commented May 13, 2025

Uh oh!

sampsyo left a comment

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

sampsyo May 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		private next = 1;
		private wait = new Map<number, (v: any) => void>();

	* Creates a new thread that begins executing function @func.
	* Creates a new thread that begins executing function `@func`.

+
+
+

                
                    No newline at end of file

Add spawn/join concurrency extension to Bril #416

Are you sure you want to change the base?

Add spawn/join concurrency extension to Bril #416

Uh oh!

Conversation

ananyagoenka commented May 13, 2025

Highlights

Uh oh!

sampsyo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants