From 98c9798cb757045b3f46573c5baa80e2cfe672aa Mon Sep 17 00:00:00 2001
From: Andrew Mitchell <32021055+mitch292@users.noreply.github.com>
Date: Fri, 25 Sep 2020 19:15:18 -0400
Subject: [PATCH] docs(std): add async and signal readme (#7683)

Resolves #7608
---
 std/async/README.md  | 85 ++++++++++++++++++++++++++++++++++++++++++++
 std/signal/README.md | 38 ++++++++++++++++++++
 2 files changed, 123 insertions(+)
 create mode 100644 std/async/README.md
 create mode 100644 std/signal/README.md

diff --git a/std/async/README.md b/std/async/README.md
new file mode 100644
index 0000000000..3470c9c723
--- /dev/null
+++ b/std/async/README.md
@@ -0,0 +1,85 @@
+# async
+
+async is a module to provide help with aysncronous tasks.
+
+# usage
+
+The following functions and class are exposed in `mod.ts`
+
+## deferred
+
+Creates a Promise with the `reject` and `resolve` functions.
+
+```typescript
+import { deferred } from "https://deno.land.std/async/mod.ts";
+
+const p = deferred<number>();
+// ...
+p.resolve(42);
+```
+
+## delay
+
+Resolve a Promise after a given amount of milliseconds
+
+```typescript
+import { delay } from "https://deno.land.std/async/mod.ts";
+
+// ...
+const delayedPromise = delay(100);
+const result = await delayedPromise;
+// ...
+```
+
+## MuxAsyncIterator
+
+The MuxAsyncIterator class multiplexes multiple async iterators into a single
+stream.
+
+The class makes an assumption that the final result (the value returned and not
+yielded from the iterator) does not matter. If there is any result, it is
+discarded.
+
+```typescript
+import { MuxAsyncIterator } from "https://deno.land.std/async/mod.ts";
+
+async function* gen123(): AsyncIterableIterator<number> {
+  yield 1;
+  yield 2;
+  yield 3;
+}
+
+async function* gen456(): AsyncIterableIterator<number> {
+  yield 4;
+  yield 5;
+  yield 6;
+}
+
+const mux = new MuxAsyncIterator<number>();
+mux.add(gen123());
+mux.add(gen456());
+for await (const value of mux) {
+  // ...
+}
+// ..
+```
+
+## pooledMap
+
+Transform values from an (async) iterable into another async iterable. The
+transforms are done concurrently, with a max concurrency defined by the
+poolLimit.
+
+```typescript
+import { pooledMap } from "https://deno.land.std/async/mod.ts";
+
+const results = pooledMap(
+  2,
+  [1, 2, 3],
+  (i) => new Promise((r) => setTimeout(() => r(i), 1000)),
+);
+
+for await (const value of results) {
+  // ...
+}
+```
diff --git a/std/signal/README.md b/std/signal/README.md
new file mode 100644
index 0000000000..f58c742b9e
--- /dev/null
+++ b/std/signal/README.md
@@ -0,0 +1,38 @@
+# signal
+
+signal is a module used to capture and monitor OS signals
+
+# usage
+
+The following functions are exposed in `mod.ts`
+
+## signal
+
+Generates an AsyncIterable which can be awaited on for one or more signals.
+`dispose()` can be called when you are finished waiting on the events.
+
+```typescript
+import { signal } from "https://deno.land.std/signal/mod.ts";
+const sig = signal(Deno.Signal.SIGUSR1, Deno.Signal.SIGINT);
+setTimeout(() => {}, 5000); // Prevents exiting immediately
+
+for await (const _ of sig) {
+  // ..
+}
+
+// At some other point in your code when finished listening:
+sig.dispose();
+```
+
+## onSignal
+
+Registers a callback function to be called on triggering of a signal event.
+
+```typescript
+import { onSignal } from "https://deno.land.std/signal/mod.ts";
+
+const handle = onSignal(Deno.Signal.SIGINT, () => {
+  // ...
+  handle.dispose(); // de-register from receiving further events
+});
+```