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