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/threads.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 docs/threads.md

(limited to 'docs/threads.md')

diff --git a/docs/threads.md b/docs/threads.md
new file mode 100644
index 00000000..228fc8ac
--- /dev/null
+++ b/docs/threads.md
@@ -0,0 +1,111 @@
+# Threads
+
+Tomo supports POSIX threads (pthreads) through the `Thread` type. The
+recommended practice is to have each thread interact with other threads only
+through thread-safe Channels with no other shared data.
+
+## Thread Methods
+
+### `new`
+
+**Description:**  
+Creates a new thread to execute a specified function.
+
+**Usage:**  
+```tomo
+Thread.new(fn: func() -> Void) -> Thread
+```
+
+**Parameters:**
+
+- `fn`: The function to be executed by the new thread.
+
+**Returns:**  
+A new `Thread` object representing the created thread.
+
+**Example:**  
+```tomo
+>> jobs := |Int|
+>> results := |Int|
+>> thread := Thread.new(func():
+    while yes:
+        input := jobs:get()
+        results:give(input + 10
+)
+= Thread<0x12345678>
+>> jobs:give(10)
+>> results:get()
+= 11
+```
+
+---
+
+### `cancel`
+
+**Description:**  
+Requests the cancellation of a specified thread.
+
+**Usage:**  
+```tomo
+cancel(thread: Thread) -> Void
+```
+
+**Parameters:**
+
+- `thread`: The thread to cancel.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> thread:cancel()
+```
+
+---
+
+### `join`
+
+**Description:**  
+Waits for a specified thread to terminate.
+
+**Usage:**  
+```tomo
+join(thread: Thread) -> Void
+```
+
+**Parameters:**
+
+- `thread`: The thread to join.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> thread:join()
+```
+
+---
+
+### `detach`
+
+**Description:**  
+Detaches a specified thread, allowing it to run independently.
+
+**Usage:**  
+```tomo
+detach(thread: Thread) -> Void
+```
+
+**Parameters:**
+
+- `thread`: The thread to detach.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+>> thread:detach()
+```
-- 
cgit v1.2.3