@grain/stdlib 0.4.6 → 0.5.0

package/runtime/dataStructures.md

@@ -0,0 +1,391 @@
+### DataStructures.**allocateArray**
+
+```grain
+allocateArray : WasmI32 -> WasmI32
+```
+
+Allocates a new Grain array.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`numElts`|`WasmI32`|The number of elements to be contained in this array|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the array|
+
+### DataStructures.**allocateTuple**
+
+```grain
+allocateTuple : WasmI32 -> WasmI32
+```
+
+Allocates a new Grain tuple.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`numElts`|`WasmI32`|The number of elements to be contained in this tuple|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the tuple|
+
+### DataStructures.**allocateBytes**
+
+```grain
+allocateBytes : WasmI32 -> WasmI32
+```
+
+Allocates a new Grain bytes.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`size`|`WasmI32`|The number of bytes to be contained in this buffer|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the bytes|
+
+### DataStructures.**allocateString**
+
+```grain
+allocateString : WasmI32 -> WasmI32
+```
+
+Allocates a new Grain string.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`size`|`WasmI32`|The size (in bytes) of the string to allocate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the string|
+
+### DataStructures.**allocateInt32**
+
+```grain
+allocateInt32 : () -> WasmI32
+```
+
+Allocates a new Int32.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the empty Int32|
+
+### DataStructures.**newInt32**
+
+```grain
+newInt32 : WasmI32 -> WasmI32
+```
+
+Allocates a new Int32 with a prepopulated value
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`WasmI32`|The value to store|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the Int32|
+
+### DataStructures.**allocateInt64**
+
+```grain
+allocateInt64 : () -> WasmI32
+```
+
+Allocates a new Int64.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the empty Int64|
+
+### DataStructures.**newInt64**
+
+```grain
+newInt64 : WasmI64 -> WasmI32
+```
+
+Allocates a new Int64 with a prepopulated value
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`WasmI64`|The value to store|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the Int64|
+
+### DataStructures.**allocateFloat32**
+
+```grain
+allocateFloat32 : () -> WasmI32
+```
+
+Allocates a new Float32.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the empty Float32|
+
+### DataStructures.**newFloat32**
+
+```grain
+newFloat32 : WasmF32 -> WasmI32
+```
+
+Allocates a new Float32 with a prepopulated value
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`WasmF32`|The value to store|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|the pointer to the Float32|
+
+### DataStructures.**allocateFloat64**
+
+```grain
+allocateFloat64 : () -> WasmI32
+```
+
+Allocates a new Float64.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the empty Float64|
+
+### DataStructures.**newFloat64**
+
+```grain
+newFloat64 : WasmF64 -> WasmI32
+```
+
+Allocates a new Float64 with a prepopulated value
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`WasmF64`|The value to store|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the Float64|
+
+### DataStructures.**allocateRational**
+
+```grain
+allocateRational : () -> WasmI32
+```
+
+Allocates a new Rational.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the empty Rational|
+
+### DataStructures.**newRational**
+
+```grain
+newRational : (WasmI32, WasmI32) -> WasmI32
+```
+
+Allocates a new Rational with a prepopulated value
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`WasmI32`|The numerator value to store|
+|`value`|`WasmI32`|The denominator value to store|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the Rational|
+
+### DataStructures.**loadAdtVariant**
+
+```grain
+loadAdtVariant : WasmI32 -> WasmI32
+```
+
+Load the (tagged) variant of an ADT.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`ptr`|`WasmI32`|Untagged pointer to the ADT|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The (tagged) ADT variant id|
+
+### DataStructures.**stringSize**
+
+```grain
+stringSize : WasmI32 -> WasmI32
+```
+
+Load an untagged string's size.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`ptr`|`WasmI32`|Untagged pointer to the string|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The string size (in bytes)|
+
+### DataStructures.**bytesSize**
+
+```grain
+bytesSize : WasmI32 -> WasmI32
+```
+
+Load an untagged Bytes' size.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`ptr`|`WasmI32`|Untagged pointer to the Bytes|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The Bytes size (in bytes)|
+
+### DataStructures.**tagSimpleNumber**
+
+```grain
+tagSimpleNumber : WasmI32 -> Number
+```
+
+Tag a simple number.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`num`|`WasmI32`|The number to tag|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The tagged number|
+
+### DataStructures.**untagSimpleNumber**
+
+```grain
+untagSimpleNumber : Number -> WasmI32
+```
+
+Untag a simple number.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`num`|`Number`|The number to untag|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The untagged number|
+
+### DataStructures.**tagChar**
+
+```grain
+tagChar : WasmI32 -> Char
+```
+
+Tag a char.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`num`|`WasmI32`|The usv to tag|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The tagged char|
+
+### DataStructures.**untagChar**
+
+```grain
+untagChar : Char -> WasmI32
+```
+
+Untag a char.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`num`|`Char`|The char to untag|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The untagged usv|
+

package/runtime/debug.md

@@ -0,0 +1,6 @@
+### Debug.**debug**
+
+```grain
+debug : a -> Void
+```
+

package/runtime/equal.gr

@@ -1,4 +1,4 @@
-/* grainc-flags --compilation-mode=runtime */
+/* grainc-flags --no-pervasives */
 
 import WasmI32, {
   eq as (==),
@@ -14,7 +14,6 @@ import WasmI32, {
 } from "runtime/unsafe/wasmi32"
 import WasmI64 from "runtime/unsafe/wasmi64"
 import Tags from "runtime/unsafe/tags"
-import Memory from "runtime/unsafe/memory"
 
 primitive (!): Bool -> Bool = "@not"
 primitive (||): (Bool, Bool) -> Bool = "@or"
@@ -22,8 +21,10 @@ primitive (&&): (Bool, Bool) -> Bool = "@and"
 
 import { isNumber, numberEqual } from "runtime/numbers"
 
+@unsafe
 let cycleMarker = 0x80000000n
 
+@unsafe
 let rec heapEqualHelp = (heapTag, xptr, yptr) => {
   match (heapTag) {
     t when t == Tags._GRAIN_ADT_HEAP_TAG => {
@@ -157,22 +158,6 @@ let rec heapEqualHelp = (heapTag, xptr, yptr) => {
         result
       }
     },
-    t when t == Tags._GRAIN_CHAR_HEAP_TAG => {
-      let byte = WasmI32.load8U(xptr, 4n)
-      let n = if ((byte & 0x80n) == 0x00n) {
-        1n
-      } else if ((byte & 0xF0n) == 0xF0n) {
-        4n
-      } else if ((byte & 0xE0n) == 0xE0n) {
-        3n
-      } else {
-        2n
-      }
-      // WebAssembly is little-endian, so bytes are in reverse order
-      let x = WasmI32.load(xptr, 4n) << (4n - n) * 8n
-      let y = WasmI32.load(yptr, 4n) << (4n - n) * 8n
-      x == y
-    },
     t when t == Tags._GRAIN_TUPLE_HEAP_TAG => {
       let xsize = WasmI32.load(xptr, 4n)
       let ysize = WasmI32.load(yptr, 4n)
@@ -222,10 +207,7 @@ let rec heapEqualHelp = (heapTag, xptr, yptr) => {
   }
 }
 
+@unsafe
 export let rec equal = (x: a, y: a) => {
-  let ret = equalHelp(WasmI32.fromGrain(x), WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(equal))
-  ret
+  equalHelp(WasmI32.fromGrain(x), WasmI32.fromGrain(y))
 }

package/runtime/equal.md

@@ -0,0 +1,6 @@
+### Equal.**equal**
+
+```grain
+equal : (a, a) -> Bool
+```
+

package/runtime/exception.md

@@ -0,0 +1,30 @@
+### Exception.**Option**
+
+```grain
+type Option<a>
+```
+
+### Exception.**printers**
+
+```grain
+printers : WasmI32
+```
+
+### Exception.**dangerouslyRegisterBasePrinter**
+
+```grain
+dangerouslyRegisterBasePrinter : a -> Void
+```
+
+### Exception.**dangerouslyRegisterPrinter**
+
+```grain
+dangerouslyRegisterPrinter : a -> Void
+```
+
+### Exception.**printException**
+
+```grain
+printException : Exception -> Void
+```
+

package/runtime/gc.gr

@@ -45,8 +45,18 @@ primitive unbox: Box<a> -> a = "@unbox"
 
 exception DecRefError
 
-export let decimalCount32 = box((n: WasmI32) => 0n)
-export let utoa32Buffered = box((a: WasmI32, b: WasmI32, c: WasmI32) => void)
+let decimalCount32Dummy = (n: WasmI32) => 0n
+let utoa32BufferedDummy = (a: WasmI32, b: WasmI32, c: WasmI32) => void
+
+// When these boxes are backpatched, the reference count of each function will
+// fall to zero which would cause them to be freed. We can't free anything that
+// got allocated in runtime mode (since that memory space is not managed by the
+// GC, so here we prevent that by manually setting a higher refcount.
+WasmI32.store(WasmI32.fromGrain(decimalCount32Dummy) - 8n, 2n, 0n)
+WasmI32.store(WasmI32.fromGrain(utoa32BufferedDummy) - 8n, 2n, 0n)
+
+export let decimalCount32 = box(decimalCount32Dummy)
+export let utoa32Buffered = box(utoa32BufferedDummy)
 
 let mut _DEBUG = false
 
@@ -205,6 +215,14 @@ let rec decRef = (userPtr: WasmI32, ignoreZeros: Bool) => {
   }
 }, decRefChildren = (userPtr: WasmI32) => {
   match (WasmI32.load(userPtr, 0n)) {
+    t when t == Tags._GRAIN_BOXED_NUM_HEAP_TAG => {
+      let tag = WasmI32.load(userPtr, 4n)
+      if (userPtr == Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) {
+        // decRef underlying BigInts
+        ignore(decRef(WasmI32.load(userPtr, 8n), false))
+        ignore(decRef(WasmI32.load(userPtr, 12n), false))
+      }
+    },
     t when t == Tags._GRAIN_ADT_HEAP_TAG => {
       let arity = WasmI32.load(userPtr, 16n)
       let maxOffset = arity * 4n
@@ -242,7 +260,6 @@ let rec decRef = (userPtr: WasmI32, ignoreZeros: Bool) => {
   }
 }
 
-export let decRefIgnoreZeros = userPtr => decRef(userPtr, true)
 export let decRef = userPtr => decRef(userPtr, false)
 
 // For debugging:

package/runtime/gc.md

@@ -0,0 +1,36 @@
+### Gc.**decimalCount32**
+
+```grain
+decimalCount32 : Box<WasmI32 -> WasmI32>
+```
+
+### Gc.**utoa32Buffered**
+
+```grain
+utoa32Buffered : Box<(WasmI32, WasmI32, WasmI32) -> Void>
+```
+
+### Gc.**malloc**
+
+```grain
+malloc : WasmI32 -> WasmI32
+```
+
+### Gc.**free**
+
+```grain
+free : WasmI32 -> Void
+```
+
+### Gc.**incRef**
+
+```grain
+incRef : WasmI32 -> WasmI32
+```
+
+### Gc.**decRef**
+
+```grain
+decRef : WasmI32 -> WasmI32
+```
+

package/runtime/malloc.gr

@@ -30,6 +30,8 @@ primitive (||): (Bool, Bool) -> Bool = "@or"
 
 primitive throw: Exception -> a = "@throw"
 
+primitive heapBase: WasmI32 = "@heap.base"
+
 /* UNDERSTANDING THE STRUCTURE OF THE FREE LIST
  * The original K&R definition for the free list entry type was the following:
  *
@@ -80,7 +82,7 @@ export let _RESERVED_RUNTIME_SPACE = 0x4000n
  * The base the heap. The block at this address will be size 0 and
  * serve as the root of the free list.
  */
-let _BASE = _RESERVED_RUNTIME_SPACE
+let _BASE = heapBase + _RESERVED_RUNTIME_SPACE
 
 /**
  * The start pointer of the heap.
@@ -114,8 +116,8 @@ let setSize = (ptr: WasmI32, val: WasmI32) => {
 /**
  * Requests that the heap be grown by the given number of bytes.
  *
- * @param nbytes: WasmI32 - The number of bytes requested
- * @return WasmI32 - If unsuccessful, -1. Otherwise, the pointer to the beginning of the extended region.
+ * @param nbytes: The number of bytes requested
+ * @returns The pointer to the beginning of the extended region if successful or -1 otherwise
  */
 let growHeap = (nbytes: WasmI32) => {
   let mut reqSize = 0n
@@ -162,7 +164,7 @@ let growHeap = (nbytes: WasmI32) => {
 /**
  * Frees the given allocated pointer.
  *
- * @param ap: WasmI32 - The pointer to free
+ * @param ap: The pointer to free
  */
 export let free = (ap: WasmI32) => {
   let mut blockPtr = ap - 8n // 8 bytes for malloc header
@@ -210,8 +212,8 @@ export let free = (ap: WasmI32) => {
  * (if you can't tell from the fact that the name is reminiscient
  *  of the 1970s, the name of this function is taken from K&R).
  *
- * @param nbytes: WasmI32 - The number of bytes to try to grow the heap by
- * @return WasmI32 - If successful, a pointer to the start of the free list. If not successful, -1.
+ * @param nbytes: The number of bytes to try to grow the heap by
+ * @returns A pointer to the start of the free list if successful or -1 otherwise
  */
 let morecore = (nbytes: WasmI32) => {
   let origSize = heapSize
@@ -235,8 +237,8 @@ let morecore = (nbytes: WasmI32) => {
 /**
  * Allocates the requested number of bytes, returning a pointer.
  *
- * @param nbytes: WasmI32 - The number of bytes to allocate
- * @return WasmI32 - The pointer to the allocated region (8-byte aligned), or -1 if the allocation failed.
+ * @param nbytes: The number of bytes to allocate
+ * @returns The pointer to the allocated region (8-byte aligned) or -1 if the allocation failed
  */
 export let malloc = (nb: WasmI32) => {
   let mut nbytes = nb
@@ -300,10 +302,10 @@ export let malloc = (nb: WasmI32) => {
 }
 
 /**
- * Returns the current free list pointer
- * (used for debugging)
+ * Returns the current free list pointer.
+ * Used for debugging.
  *
- * @return WasmI32 - The free list pointer
+ * @returns The free list pointer
  */
 export let getFreePtr = () => {
   freePtr

package/runtime/malloc.md

@@ -0,0 +1,55 @@
+### Malloc.**_RESERVED_RUNTIME_SPACE**
+
+```grain
+_RESERVED_RUNTIME_SPACE : WasmI32
+```
+
+### Malloc.**free**
+
+```grain
+free : WasmI32 -> Void
+```
+
+Frees the given allocated pointer.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`ap`|`WasmI32`|The pointer to free|
+
+### Malloc.**malloc**
+
+```grain
+malloc : WasmI32 -> WasmI32
+```
+
+Allocates the requested number of bytes, returning a pointer.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`nbytes`|`WasmI32`|The number of bytes to allocate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The pointer to the allocated region (8-byte aligned) or -1 if the allocation failed|
+
+### Malloc.**getFreePtr**
+
+```grain
+getFreePtr : () -> WasmI32
+```
+
+Returns the current free list pointer.
+Used for debugging.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`WasmI32`|The free list pointer|
+