From 45762caffec3368697bd8597e203b8cb74323a21 Mon Sep 17 00:00:00 2001
From: Evan Williams <emw236@cornell.edu>
Date: Mon, 11 Dec 2023 14:32:52 -0500
Subject: [PATCH] fixed documentation

---
 bril-rs/src/program.rs |  5 +++
 docs/lang/async.bril   | 81 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 docs/lang/async.bril

diff --git a/bril-rs/src/program.rs b/bril-rs/src/program.rs
index 54c02e5ff..0b6cfa94f 100644
--- a/bril-rs/src/program.rs
+++ b/bril-rs/src/program.rs
@@ -481,14 +481,19 @@ pub enum ValueOps {
     /// <https://capra.cs.cornell.edu/bril/lang/memory.html#operations>
     #[cfg(feature = "memory")]
     PtrAdd,
+    /// <<https://capra.cs.cornell.edu/bril/lang/async.html>>
     #[cfg(feature = "async")]
     Resolve,
+    /// <<https://capra.cs.cornell.edu/bril/lang/async.html>>
     #[cfg(feature = "async")]
     CompareAndSwap,
+    /// <<https://capra.cs.cornell.edu/bril/lang/async.html>>
     #[cfg(feature = "async")]
     LoadAtomic,
+    /// <<https://capra.cs.cornell.edu/bril/lang/async.html>>
     #[cfg(feature = "async")]
     SwapAtomic,
+    /// <<https://capra.cs.cornell.edu/bril/lang/async.md>>
     #[cfg(feature = "async")]
     NewAtomic,
 }
diff --git a/docs/lang/async.bril b/docs/lang/async.bril
new file mode 100644
index 000000000..b50575abf
--- /dev/null
+++ b/docs/lang/async.bril
@@ -0,0 +1,81 @@
+Asynchronous Bril
+========================
+
+This extension gives Bril users access to 
+[promises](https://en.wikipedia.org/wiki/Futures_and_promises) and 
+[atomics](https://wiki.osdev.org/Atomic_operation). Read more about the 
+implementation in our blog. 
+
+Install 
+-------
+
+The extension comes with the [Rust library](https://capra.cs.cornell.edu/bril/tools/rust.html)
+for Bril. Feel free to walk through the setup and installation for Rust mentioned 
+in the documentation. 
+
+Syntax 
+-------
+
+We have added a few new pices of syntax to the language: 
+- `Promise<T>`: allows you to define a *promise* with return type `T`. Upon 
+encountering a function defined with a `Promise<T>` return type, a thread is 
+immediately started.
+- `Resolve`: allows you to resolve a promise. Will return a variable of type `T`
+if the promise being resolved is of type `Promise<T>`
+- `atomicint`: allows you to create variables of type `atomicint`, which, 
+as the name suggests, represents an atomic integer. 
+
+Examples
+-------
+
+Here is an example of promises in Bril:
+```
+@main {
+  size: int = const 4;
+  size2: bool = const false;
+  prom: promise<int> = call @mod size;
+  prom2: promise<bool> = call @mod2 size2;
+  x : int = resolve prom;
+  y : bool = resolve prom2;
+  print x;
+  print y;
+}
+
+@mod(r: int): promise<int> {
+  ret r;
+}
+
+@mod2(r: bool): promise<bool> {
+  ret r;
+}
+```
+
+Note that the right-hand side of a promise type is a function call. Upon calling
+`resolve`, we are able to assign the output of the function call to a normal 
+Bril variable (in this case we support `int` and `bool`). 
+
+Here is an example of atomics in Bril:
+```
+@main {
+  one : int = const 1;
+  size : atomicint = newatomic one;
+  expect : int = const 1;
+  upd : int = const 2;
+  res : int = cas size expect upd;
+
+  three : int = const 3;
+  res1 : int = loadatomic size;
+  res2 : int = swapatomic size three;
+  res3 : int = loadatomic size;
+  print res;
+  print res1;
+  print res2;
+  print res3;
+}
+```
+
+Note that to create an `atomicint`, we introduce a constructor `newatomic`. 
+The constructor takes in a normal Bril integer and uses it to produce the new
+atomic variable. Further, the functions `loadatomic` and `swapatomic` can be 
+used to manipulate atomic variables, in addition to the function `cas` (which 
+stands for Compare-and-Swap). 
\ No newline at end of file