git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/docs/userspace/threads/overview.md
82 lines 4.1 kB history raw
1+++
2title = "Overview"
3weight = 1
4template = "doc.html"
5+++
7Urbit code lives in the following basic categories:
9- Runtime (Nock interpreter, persistence engine, IO drivers, jets)
10- Kernel vanes (managed by Arvo)
11- Userspace agents (managed by Gall, permanent state)
12- Userspace threads (managed by Spider, transient state)
14This describes the last category: Threads.
16A thread is a monadic function that takes arguments and produces a
17result. It may perform input and output while running, so it is not a
18pure function. It may fail.
20An agent's strength is that it's permanent and bulletproof. All state
21transitions are defined, and each action it performs is a transaction.
22Code upgrades preserve existing state.
24An agent's weakness is complex input and output. Since each state
25transition must be explicitly handled, the complexity of an agent
26explodes with the amount of IO it handles. At best, this results in
27long and complex code; at worst, unexpected states are mishandled,
28corrupting permanent state.
30A thread's strength is that it can easily perform complex IO operations.
31It uses what's often called the IO monad (plus the exception monad) to
32provide a natural framework for IO.
34A thread's weakness is that it's impermanent and may fail unexpectedly.
35In most of its intermediate states, it expects only a small number of
36events (usually one), so if it receives anything it didn't expect, it
37fails. When code is upgraded, it's impossible to upgrade a running
38thread, so it fails.
40Thus, for anything that needs to be permament, use an agent. When you
41need to do a long or complex sequence of IO operations, reduce that to a
42single logical IO operation by spinning it out into a thread. If you
43only change your agent's state in response to success of the thread, an
44IO failure will never result in partially applied state changes.
46A thread may also be run from the dojo by prefixing its name with `-`
47and giving it any arguments it requires. If alone, any result will be
48printed to the screen; else the output may be piped into an agent or
49other sinks.
51## Thread basics
53These docs walk through the fundamental things you need to know to write threads. They're focused on basic thread composition so don't touch on interacting with threads from gall agents and such. The included examples can all just be run from the dojo.
551. [Thread Fundamentals](/docs/userspace/threads/basics/fundamentals) - Basic information and overview of threads, strands, `form` & `pure`.
562. [Micgal and Bind](/docs/userspace/threads/basics/bind) - Covers using micgal and `bind` to chain strands.
573. [Strand Input](/docs/userspace/threads/basics/input) - What strands receive as input
584. [Strand Output](/docs/userspace/threads/basics/output) - What strands produce
595. [Summary](/docs/userspace/threads/basics/summary)
61## Gall
63These docs walk through the basics of interacting with threads from gall agents.
651. [Start a thread](/docs/userspace/threads/gall/start-thread)
662. [Subscribe for result](/docs/userspace/threads/gall/take-result)
673. [Subscribe for facts](/docs/userspace/threads/gall/take-facts)
684. [Stop a thread](/docs/userspace/threads/gall/stop-thread)
695. [Poke a thread](/docs/userspace/threads/gall/poke-thread)
71## How-tos & Examples
73- [Grab some JSON from a URL](/docs/userspace/threads/examples/get-json) - Here's an example of chaining a couple of external http requests for JSON.
74- [Start a child thread](/docs/userspace/threads/examples/child-thread) - Starting and managing child threads.
75- [Main Loop](/docs/userspace/threads/examples/main-loop) - Some notes and examples of the `strandio` function `main-loop`.
76- [Poke an agent](/docs/userspace/threads/examples/poke-agent) - Example of poking an agent from a thread.
77- [Scry](/docs/userspace/threads/examples/scry) - Scry arvo or an agent.
78- [Take a fact](/docs/userspace/threads/examples/take-fact) - Subscribe to an agent and receive a fact.
80## [Reference](/docs/userspace/threads/reference)
82Basic reference information. For usage of particular `strandio` functions just refer directly to `/lib/strandio/hoon` since they're largely self-explanatory.