@grain/stdlib 0.5.12 → 0.6.0

package/wasi/process.gr

@@ -0,0 +1,292 @@
+/**
+ * Utilities for accessing functionality and information about the Grain program's process.
+ *
+ * This includes things like accessing environment variables and sending signals.
+ *
+ * @example from "wasi/process" include Process
+ */
+module Process
+
+from "runtime/unsafe/wasmi32" include WasmI32
+use WasmI32.{ (+), (*), (>>), (>>>), (&), (==), (!=), (<) }
+from "runtime/unsafe/memory" include Memory
+from "runtime/wasi" include Wasi
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ tagSimpleNumber, allocateArray, allocateString }
+
+/**
+ * Signals that can be sent to the host system.
+ */
+provide enum Signal {
+  /**
+   * Hangup.
+   */
+  HUP,
+  /**
+   * Terminate interrupt signal.
+   */
+  INT,
+  /**
+   * Terminal quit signal.
+   */
+  QUIT,
+  /**
+   * Illegal instruction.
+   */
+  ILL,
+  /**
+   * Trace/breakpoint trap.
+   */
+  TRAP,
+  /**
+   * Process abort signal.
+   */
+  ABRT,
+  /**
+   * Access to an undefined portion of a memory object.
+   */
+  BUS,
+  /**
+   * Erroneous arithmetic operation.
+   */
+  FPE,
+  /**
+   * Kill.
+   */
+  KILL,
+  /**
+   * User-defined signal 1.
+   */
+  USR1,
+  /**
+   * Invalid memory reference.
+   */
+  SEGV,
+  /**
+   * User-defined signal 2.
+   */
+  USR2,
+  /**
+   * Write on a pipe with no one to read it.
+   */
+  PIPE,
+  /**
+   * Alarm clock.
+   */
+  ALRM,
+  /**
+   * Termination signal.
+   */
+  TERM,
+  /**
+   * Child process terminated, stopped, or continued.
+   */
+  CHLD,
+  /**
+   * Continue executing, if stopped.
+   */
+  CONT,
+  /**
+   * Stop executing.
+   */
+  STOP,
+  /**
+   * Terminal stop signal.
+   */
+  TSTP,
+  /**
+   * Background process attempting read.
+   */
+  TTIN,
+  /**
+   * Background process attempting write.
+   */
+  TTOU,
+  /**
+   * High bandwidth data is available at a socket.
+   */
+  URG,
+  /**
+   * CPU time limit exceeded.
+   */
+  XCPU,
+  /**
+   * File size limit exceeded.
+   */
+  XFSZ,
+  /**
+   * Virtual timer expired.
+   */
+  VTALRM,
+  PROF,
+  WINCH,
+  POLL,
+  PWR,
+  /**
+   * Bad system call.
+   */
+  SYS,
+}
+
+/**
+ * Access command line arguments.
+ *
+ * @returns `Ok(args)` of an array containing positional string arguments to the process if successful or `Err(exception)` otherwise
+ */
+@unsafe
+provide let argv = () => {
+  let argcPtr = Memory.malloc(8n)
+  let argvBufSizePtr = argcPtr + 4n
+
+  let err = Wasi.args_sizes_get(argcPtr, argvBufSizePtr)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(argcPtr)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+
+  let argc = WasmI32.load(argcPtr, 0n)
+  Memory.free(argcPtr)
+
+  let argsLength = argc * 4n
+  let arr = allocateArray(argc)
+
+  if (WasmI32.eqz(argsLength)) {
+    return Ok(WasmI32.toGrain(arr): Array<String>)
+  }
+
+  let argvBufSize = WasmI32.load(argvBufSizePtr, 0n)
+
+  let argvPtr = Memory.malloc(argc * 4n)
+  let argvBufPtr = Memory.malloc(argvBufSize)
+
+  let err = Wasi.args_get(argvPtr, argvBufPtr)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(argvPtr)
+    Memory.free(argvBufPtr)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+
+  for (let mut i = 0n; i < argsLength; i += 4n) {
+    let strPtr = WasmI32.load(argvPtr + i, 0n)
+    let mut strLength = 0n
+    while (WasmI32.load8U(strPtr + strLength, 0n) != 0n) {
+      strLength += 1n
+    }
+
+    let grainStrPtr = allocateString(strLength)
+    Memory.copy(grainStrPtr + 8n, strPtr, strLength)
+
+    WasmI32.store(arr + i, grainStrPtr, 8n)
+  }
+
+  Memory.free(argvPtr)
+  Memory.free(argvBufPtr)
+
+  return Ok(WasmI32.toGrain(arr): Array<String>)
+}
+
+/**
+ * Access environment variables.
+ *
+ * @returns `Ok(vars)` of an array containing environment variables supplied to the process if successful or `Err(exception)` otherwise
+ */
+@unsafe
+provide let env = () => {
+  let envcPtr = Memory.malloc(8n)
+  let envvBufSizePtr = envcPtr + 4n
+
+  let err = Wasi.environ_sizes_get(envcPtr, envvBufSizePtr)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(envcPtr)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  let envc = WasmI32.load(envcPtr, 0n)
+  let envvBufSize = WasmI32.load(envvBufSizePtr, 0n)
+
+  if (WasmI32.eqz(envc)) {
+    Memory.free(envcPtr)
+    return Ok([>]: Array<String>)
+  }
+
+  let envvPtr = Memory.malloc(envc * 4n)
+  let envvBufPtr = Memory.malloc(envvBufSize)
+
+  let err = Wasi.environ_get(envvPtr, envvBufPtr)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(envcPtr)
+    Memory.free(envvPtr)
+    Memory.free(envvBufPtr)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  let arr = allocateArray(envc)
+
+  let envsLength = envc * 4n
+  for (let mut i = 0n; i < envsLength; i += 4n) {
+    let strPtr = WasmI32.load(envvPtr + i, 0n)
+    let mut strLength = 0n
+    while (WasmI32.load8U(strPtr + strLength, 0n) != 0n) {
+      strLength += 1n
+    }
+
+    let grainStrPtr = allocateString(strLength)
+    Memory.copy(grainStrPtr + 8n, strPtr, strLength)
+
+    WasmI32.store(arr + i, grainStrPtr, 8n)
+  }
+
+  Memory.free(envcPtr)
+  Memory.free(envvPtr)
+  Memory.free(envvBufPtr)
+
+  return Ok(WasmI32.toGrain(arr): Array<String>)
+}
+
+/**
+ * Terminate the process normally.
+ *
+ * @param code: The value to exit with. An exit code of 0 is considered normal, with other values having meaning depending on the platform
+ * @returns `Err(exception)` if unsuccessful. Will not actually return a value if successful, as the process has ended
+ */
+@unsafe
+provide let exit = (code: Number) => {
+  let mut code = WasmI32.fromGrain(code)
+
+  if ((code & 1n) == 0n) {
+    return Err(InvalidArgument("Invalid exit code"))
+  }
+  code = code >> 1n
+  Wasi.proc_exit(code)
+  // Never actually hit because it exited
+  return Ok(void)
+}
+
+/**
+ * Send a signal to the process of the calling thread.
+ *
+ * @param signal: The signal to send
+ * @returns `Ok(void)` if successful or `Err(exception)` otherwise
+ */
+@unsafe
+provide let sigRaise = (signal: Signal) => {
+  let signal = WasmI32.fromGrain(signal)
+  let signal = WasmI32.load(signal, 12n) >> 1n
+  let err = Wasi.proc_raise(signal)
+  if (err != Wasi._ESUCCESS) {
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  return Ok(void)
+}
+
+/**
+ * Yield execution to the calling thread.
+ *
+ * @returns `Ok(void)` if successful or `Err(exception)` otherwise
+ */
+@unsafe
+provide let schedYield = () => {
+  let err = Wasi.sched_yield()
+  if (err != Wasi._ESUCCESS) {
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  return Ok(void)
+}

package/{sys → wasi}/process.md

@@ -7,7 +7,7 @@ Utilities for accessing functionality and information about the Grain program's
 This includes things like accessing environment variables and sending signals.
 
 ```grain
-import Process from "sys/process"
+from "wasi/process" include Process
 ```
 
 ## Types
@@ -53,6 +53,164 @@ enum Signal {
 
 Signals that can be sent to the host system.
 
+Variants:
+
+```grain
+HUP
+```
+
+Hangup.
+
+```grain
+INT
+```
+
+Terminate interrupt signal.
+
+```grain
+QUIT
+```
+
+Terminal quit signal.
+
+```grain
+ILL
+```
+
+Illegal instruction.
+
+```grain
+TRAP
+```
+
+Trace/breakpoint trap.
+
+```grain
+ABRT
+```
+
+Process abort signal.
+
+```grain
+BUS
+```
+
+Access to an undefined portion of a memory object.
+
+```grain
+FPE
+```
+
+Erroneous arithmetic operation.
+
+```grain
+KILL
+```
+
+Kill.
+
+```grain
+USR1
+```
+
+User-defined signal 1.
+
+```grain
+SEGV
+```
+
+Invalid memory reference.
+
+```grain
+USR2
+```
+
+User-defined signal 2.
+
+```grain
+PIPE
+```
+
+Write on a pipe with no one to read it.
+
+```grain
+ALRM
+```
+
+Alarm clock.
+
+```grain
+TERM
+```
+
+Termination signal.
+
+```grain
+CHLD
+```
+
+Child process terminated, stopped, or continued.
+
+```grain
+CONT
+```
+
+Continue executing, if stopped.
+
+```grain
+STOP
+```
+
+Stop executing.
+
+```grain
+TSTP
+```
+
+Terminal stop signal.
+
+```grain
+TTIN
+```
+
+Background process attempting read.
+
+```grain
+TTOU
+```
+
+Background process attempting write.
+
+```grain
+URG
+```
+
+High bandwidth data is available at a socket.
+
+```grain
+XCPU
+```
+
+CPU time limit exceeded.
+
+```grain
+XFSZ
+```
+
+File size limit exceeded.
+
+```grain
+VTALRM
+```
+
+Virtual timer expired.
+
+```grain
+SYS
+```
+
+Bad system call.
+
 ## Values
 
 Functions and constants included in the Process module.
@@ -60,7 +218,7 @@ Functions and constants included in the Process module.
 ### Process.**argv**
 
 ```grain
-argv : () -> Result<Array<String>, Exception>
+argv : () => Result<Array<String>, Exception>
 ```
 
 Access command line arguments.
@@ -74,7 +232,7 @@ Returns:
 ### Process.**env**
 
 ```grain
-env : () -> Result<Array<String>, Exception>
+env : () => Result<Array<String>, Exception>
 ```
 
 Access environment variables.
@@ -88,7 +246,7 @@ Returns:
 ### Process.**exit**
 
 ```grain
-exit : Number -> Result<Void, Exception>
+exit : (code: Number) => Result<Void, Exception>
 ```
 
 Terminate the process normally.
@@ -108,7 +266,7 @@ Returns:
 ### Process.**sigRaise**
 
 ```grain
-sigRaise : Signal -> Result<Void, Exception>
+sigRaise : (signal: Signal) => Result<Void, Exception>
 ```
 
 Send a signal to the process of the calling thread.
@@ -128,7 +286,7 @@ Returns:
 ### Process.**schedYield**
 
 ```grain
-schedYield : () -> Result<Void, Exception>
+schedYield : () => Result<Void, Exception>
 ```
 
 Yield execution to the calling thread.

package/wasi/random.gr

@@ -0,0 +1,77 @@
+/**
+ * System access to random values.
+ *
+ * @example from "wasi/random" include Random
+ */
+module Random
+
+from "runtime/unsafe/wasmi32" include WasmI32
+use WasmI32.{ (==), (!=) }
+from "runtime/unsafe/wasmi64" include WasmI64
+from "runtime/unsafe/memory" include Memory
+from "runtime/wasi" include Wasi
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ tagSimpleNumber, newUint32, newUint64 }
+
+/**
+ * Produce a random 32-bit integer. This function can be slow, so it's best to seed a generator if lots of random data is needed.
+ *
+ * @returns `Ok(num)` of a random Uint32 if successful or `Err(exception)` otherwise
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `randomInt32`
+ */
+@unsafe
+provide let randomUint32 = () => {
+  let buf = Memory.malloc(4n)
+
+  let err = Wasi.random_get(buf, 4n)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(buf)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  let rand = WasmI32.load(buf, 0n)
+  Memory.free(buf)
+  return Ok(WasmI32.toGrain(newUint32(rand)): Uint32)
+}
+
+/**
+ * Produce a random 64-bit integer. This function can be slow, so it's best to seed a generator if lots of random data is needed.
+ *
+ * @returns `Ok(num)` of a random Uint64 if successful or `Err(exception)` otherwise
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `randomInt64`
+ */
+@unsafe
+provide let randomUint64 = () => {
+  let buf = Memory.malloc(8n)
+
+  let err = Wasi.random_get(buf, 8n)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(buf)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  let rand = WasmI64.load(buf, 0n)
+  Memory.free(buf)
+  return Ok(WasmI32.toGrain(newUint64(rand)): Uint64)
+}
+
+/**
+ * Produce a random number. This function can be slow, so it's best to seed a generator if lots of random data is needed.
+ *
+ * @returns `Ok(num)` of a random number if successful or `Err(exception)` otherwise
+ */
+@unsafe
+provide let random = () => {
+  let buf = Memory.malloc(4n)
+
+  let err = Wasi.random_get(buf, 4n)
+  if (err != Wasi._ESUCCESS) {
+    Memory.free(buf)
+    return Err(Wasi.SystemError(tagSimpleNumber(err)))
+  }
+  let rand = WasmI32.load(buf, 0n)
+  Memory.free(buf)
+  return Ok(tagSimpleNumber(rand))
+}

package/wasi/random.md

@@ -0,0 +1,80 @@
+---
+title: Random
+---
+
+System access to random values.
+
+```grain
+from "wasi/random" include Random
+```
+
+## Values
+
+Functions and constants included in the Random module.
+
+### Random.**randomUint32**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Originally named `randomInt32`</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+randomUint32 : () => Result<Uint32, Exception>
+```
+
+Produce a random 32-bit integer. This function can be slow, so it's best to seed a generator if lots of random data is needed.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<Uint32, Exception>`|`Ok(num)` of a random Uint32 if successful or `Err(exception)` otherwise|
+
+### Random.**randomUint64**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Originally named `randomInt64`</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+randomUint64 : () => Result<Uint64, Exception>
+```
+
+Produce a random 64-bit integer. This function can be slow, so it's best to seed a generator if lots of random data is needed.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<Uint64, Exception>`|`Ok(num)` of a random Uint64 if successful or `Err(exception)` otherwise|
+
+### Random.**random**
+
+```grain
+random : () => Result<Number, Exception>
+```
+
+Produce a random number. This function can be slow, so it's best to seed a generator if lots of random data is needed.
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<Number, Exception>`|`Ok(num)` of a random number if successful or `Err(exception)` otherwise|
+