Thread DocumentationWorker(s): ~tinnus-napbus Reward: 1 Stars Completed
Thread Documentation Bounty
The official thread documentation 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.
Fortunately, 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.
This bounty is detailed for clarity, but the individual sections shouldn't take too long to write and don't need to be extremely long.
spiderusage in Gall
- calling from the dojo with
spidermanages its threads
not in scope
- Walk through building a thread that composes multiple threads
- Will be all from the Dojo using
-, no Gall
- Should include the following calls
- setting a timeout
- pass cards to Arvo/Gall
- HTTP call
- read a file from Clay
lib/strand.hooncode to explain
- explain how all threads MUST take
strand-inputas an argument
- explain how
strand-inputto threads and how it determines which threads to send to.
- Call out to outside web services, chaining calls in the manner of promises/async in other languages
- make system calls to Arvo
- receive/handle responses from Arvo
spiderto integrate with Gall
backofffor calls that may fail
This 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
- as a learner with Hoon knowledge, I will be able to build a mental model of how
spidermanages threads, sends input to them, and chains them together.
;<will be demystified and explained in very simple, mechanical ways.
- 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.
- as a moderately motivated autodidact with Hoon knowledge I should be able to start writing
tedthreads for Dojo usage immediately, with no other outside materials or informal help needed
- as a Gall app developer or maintainer, I should be able to integrate threads into my Gall apps
~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.
Complete the bounty
1 stars Everything in "sections" is done.