From 67e8f2dea0d4eec20a839d47f1fa6302a4a5f733 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Mon, 19 Aug 2024 00:23:02 -0400
Subject: Move docs into one folder

---
 docs/channels.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 docs/channels.md

(limited to 'docs/channels.md')

diff --git a/docs/channels.md b/docs/channels.md
new file mode 100644
index 00000000..88cb46ff
--- /dev/null
+++ b/docs/channels.md
@@ -0,0 +1,181 @@
+# Channels
+
+Channels are a thread-safe message queue for communicating between threads,
+although they can also be used as a general-purpose queue.
+
+## Syntax
+
+The syntax to create a channel is `|:T|`, where `T` is the type that will be
+passed through the channel. You can also specify a maximum size for the
+channel, which will cause giving to block until the recipient has gotten from
+the channel if the maximum size is reached.
+
+```tomo
+channel := |:Int|
+channel:give(10)
+channel:give(20)
+>> channel:get()
+= 10
+>> channel:get()
+= 20
+
+small_channel := |:Int; max_size=5|
+```
+
+## Channel Methods
+
+### `give`
+
+**Description:**  
+Adds an item to the channel.
+
+**Usage:**  
+```markdown
+give(channel:|T|, item: T, where: Where = Where.End) -> Void
+```
+
+**Parameters:**
+
+- `channel`: The channel to which the item will be added.
+- `item`: The item to add to the channel.
+- `where`: Where to put the item (at the `Start` or `End` of the queue).
+  `Anywhere` defaults to `End`.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> channel:give("Hello")
+```
+
+---
+
+### `give_all`
+
+**Description:**  
+Adds multiple items to the channel.
+
+**Usage:**  
+```markdown
+give_all(channel:|T|, items: [T], where: Where = Where.End) -> Void
+```
+
+**Parameters:**
+
+- `channel`: The channel to which the items will be added.
+- `items`: The array of items to add to the channel.
+- `where`: Where to put the items (at the `Start` or `End` of the queue).
+  `Anywhere` defaults to `End`.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> channel:give_all([1, 2, 3])
+```
+
+---
+
+### `get`
+
+**Description:**  
+Removes and returns an item from the channel. If the channel is empty, it waits until an item is available.
+
+**Usage:**  
+```markdown
+get(channel:|T|, where: Where = Where.Start) -> T
+```
+
+**Parameters:**
+
+- `channel`: The channel from which to remove an item.
+- `where`: Where to get the item from (from the `Start` or `End` of the queue).
+  `Anywhere` defaults to `Start`.
+
+**Returns:**  
+The item removed from the channel.
+
+**Example:**  
+```markdown
+>> channel:peek()
+= "Hello"
+```
+
+---
+
+### `peek`
+
+**Description:**  
+Returns the next item that will come out of the channel, but without removing
+it. If the channel is empty, it waits until an item is available.
+
+**Usage:**  
+```markdown
+peek(channel:|T|, where: Where = Where.Start) -> T
+```
+
+**Parameters:**
+
+- `channel`: The channel from which to remove an item.
+- `where`: Which end of the channel to peek from (the `Start` or `End`).
+  `Anywhere` defaults to `Start`.
+
+**Returns:**  
+The item removed from the channel.
+
+**Example:**  
+```markdown
+>> channel:get()
+= "Hello"
+```
+
+---
+
+### `clear`
+
+**Description:**  
+Removes all items from the channel.
+
+**Usage:**  
+```markdown
+clear(channel:|T|) -> Void
+```
+
+**Parameters:**
+
+- `channel`: The mutable reference to the channel.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```markdown
+>> channel:clear()
+```
+
+---
+
+### `view`
+
+**Description:**  
+Returns a list of all items currently in the channel without removing them.
+
+**Usage:**  
+```markdown
+channel:view() -> [T]
+```
+
+**Parameters:**
+
+- `channel`: The channel to view.
+
+**Returns:**  
+An array of items currently in the channel.
+
+**Example:**  
+```markdown
+>> channel:view()
+= [1, 2, 3]
+```
-- 
cgit v1.2.3