git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/grants/thread-documentation.md
85 lines 3.5 kB history raw
1+++
2title = "Thread Documentation"
3date = "2021-02-17"
5[taxonomies]
6grant_type = [ "Bounty" ]
7grant_category = [ "Documentation" ]
9[extra]
10image = ""
11description = "Document, explain, and give simple howtos for the usage patterns of threads in the Dojo and Gall agents."
12reward = "1 star"
13assignee = "~tinnus-napbus"
14id = "4948904"
15completed = true
16link = ""
17+++
19# Thread Documentation Bounty
21The [official thread documentation](https://urbit.org/docs/tutorials/arvo/gall/#threads) is accurate and helpful, but it's a very thin combination of explainer (production code), how-to, and reference. It's a nice starting point, but it's not sufficient to let a typical Urbit autodidact enthusiast get fully comfortable with threads. As a result, they are often an uncomfortable/unused part of the Urbit system, even though they are useful and robust.
23Fortunately, the amount of implicit knowledge needed to build a strong mental model of threads and begin using them in Urbit applications. By expanding the explainer/tutorial/howto/reference and delineating them more clearly, we can expose this part of Urbit to devs.
25This bounty is detailed for clarity, but the individual sections shouldn't take too long to write and don't need to be extremely long.
27## scope
29- `ted` directory
30- `spider` usage in Gall
31- calling from the dojo with `-`
32- the `bind`/`;<` chaining model
33- how `spider` manages its threads
35### not in scope
37- aqua
39## sections
41### tutorial
43- Walk through building a thread that composes multiple threads
44- Will be all from the Dojo using `-`, no Gall
45- Should include the following calls
46 - setting a timeout
47 - pass cards to Arvo/Gall
48 - HTTP call
49 - read a file from Clay
51### explainer
53- use `lib/strand.hoon` code to explain `bind` and the `%wait` etc. objects
54- explain how all threads MUST take `strand-input` as an argument
55- explain how `spider` sends `strand-input` to threads and how it determines which threads to send to.
57### how-to
59- Call out to outside web services, chaining calls in the manner of promises/async in other languages
60- make system calls to Arvo
61- receive/handle responses from Arvo
62- use `spider` to integrate with Gall
63- use `retry` and `backoff` for calls that may fail
65### reference
67This can be thin for now, because most necessary thread functions are in `lib/strandio.hoon`, and we don't need to just cut-and-paste that. Just make a quick list of functionality in `lib/strandio` or edit the one in the current thread docs
69## user stories
71- as a learner with Hoon knowledge, I will be able to build a mental model of how `spider` manages threads, sends input to them, and chains them together. `bind` and `;<` will be demystified and explained in very simple, mechanical ways.
72- as a Hoon learner with prior monad experience, I should be able to get a feel for the similarities of IO monads and Urbit threads, and develop strong intuitions for the more mechanical nature of Urbit ones.
73- as a moderately motivated autodidact with Hoon knowledge I should be able to start writing `ted` threads for Dojo usage immediately, with no other outside materials or informal help needed
74- as a Gall app developer or maintainer, I should be able to integrate threads into my Gall apps
76## resources available
78`~timluc-miptev` will be available to whomever does the bounty to explain things, work through any tough spots, and connect to useful people if necessary.
80## Milestones
82### Complete the bounty
841 stars
85Everything in "sections" is done.