From 43b4af23f84c27dada7a3515a7661f6311e4b3ba Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 18 Aug 2024 18:23:32 -0400
Subject: API documentation

---
 api/threads.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 api/threads.md

(limited to 'api/threads.md')

diff --git a/api/threads.md b/api/threads.md
new file mode 100644
index 00000000..b6ae5138
--- /dev/null
+++ b/api/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:pop()
+        results:push(input + 10
+)
+= Thread<0x12345678>
+>> jobs:push(10)
+>> results:pop()
+= 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