A thread is like a transient gall agent. Unlike an agent, it can end and it can fail. The primary uses for threads are:
- Complex IO, like making a bunch of external API calls where each call depends on the last. Doing this in an agent significantly increases its complexity and the risk of a mishandled intermediary state corrupting permanent state. If you spin the IO out into a thread, your agent only has to make one call to the thread and receive one response.
- Testing - threads are very useful for writing complex tests for your agents.
Threads are managed by the gall agent called
Threads live in the
ted directory of each desk. For example, in a desk named
%sandbox├──app├──gen├──lib├──mar├──sur└──ted <-├──foo│ └──bar.hoon└──baz.hoon
From the dojo,
ted/baz.hoon can be run with
-sandbox!foo-bar. Threads in the
%base desk can just be run like
-foo, but all others must have the format
NOTE: When the dojo sees the
- prefix it automatically handles creating a thread ID, composing the argument, poking the
spider gall agent and subscribing for the result. Running a thread from another context (eg. a gall agent) requires doing these things explicitly and is outside the scope of this particular tutorial.
Libraries and Structures
There are three files that matter:
/sur/spider/hoon- this contains a few simple structures used by spider. It's not terribly useful except it imports libstrand, so you'll typically get
/lib/strand/hoon- this contains all the main functions and structures for strands (a thread is a running strand), and you'll refer to this fairly frequently.
/lib/strandio/hoon- this contains a large collection of ready-made functions for use in threads. You'll likely use many of these when you write threads, so it's very useful.
/sur/spider/hoon defines a thread as:
+$ thread $-(vase _*form:(strand ,vase))
That is, a gate which takes a
vase and returns the
form of a
strand that produces a
vase. This is a little confusing and we'll look at each part in detail later. For now, note that the thread doesn't just produce a result, it actually produces a strand that takes input and produces output from which a result can be extracted. It works something like this:
This is because threads typically do a bunch of I/O so it can't just immediately produce a result and end. Instead the strand will get some input, produce output, get some new input, produce new output, and so forth, until they eventually produce a
%done with the actual final result.
Strands are the building blocks of threads. A thread will typically compose multiple strands.
A strand is a function of
strand-input:strand -> output:strand and is defined in
/lib/strand/hoon. You can see the details of
strand-input here and
output:strand here. At this stage you don't need to know the nitty-gritty but it's helpful to have a quick look through. We'll discuss these things in more detail later.
A strand is a core that has three important arms:
form- the mold of the strand
pure- produces a strand that does nothing except return a value
bind- monadic bind, like
We'll discuss each of these arms later.
A strand must be specialised to produce a particular type like
(strand ,<type>). As previously mentioned, a
thread produces a
vase so is specialised like
(strand ,vase). Within your thread you'll likely compose multiple strands which produce different types like
(strand ,[path cage]), etc, but the thread itself will always come back to a
Strands are conventionally given the face
=/ m (strand ,vase)...
NOTE: a comma prefix as in
,vase is the irregular form of
^: which is a gate that returns the sample value if it's of the correct type, but crashes otherwise.
Form and Pure
form arm is the mold of the strand, suitable for casting. The two other arms produce
forms so you'll cast everything to this like:
=/ m (strand ,@ud)^- form:m...
Pure produces a strand that does nothing except return a value. So,
(pure:(strand ,@tas) %foo) is a strand that produces
%foo without doing any IO.
A trivial thread
/- spider=, strand=strand:spider^- thread:spider|= arg=vase=/ m (strand ,vase)^- form:m(pure:m arg)
The above code is a simple thread that just returns its argument, and it's a good boilerplate to start from.
Save the above code as a file in
|commit it. Run it with
-mythread 'foo', you should see the following:
> -mythread 'foo'[~ 'foo']
NOTE: The dojo wraps arguments in a unit so that's why it's
[~ 'foo'] rather than just
We'll go through it line-by line.
/- spider=, strand=strand:spider
First we import
/sur/spider/hoon which includes
/lib/strand/hoon and give the latter the face
strand for convenience.
We make it a thread by casting it to
We create a gate that takes a vase, the first part of the previously mentioned thread definition.
=/ m (strand ,vase)
Inside the gate we create our
strand specialised to produce a
vase and give it the canonical face
We cast the output to
form - the mold of the strand we created.
Finally we call
pure with the gate input
arg as its argument. Since
arg is a
vase it will return the
form of a
strand which produces a
vase. Thus we've created a thread in accordance with its type definition.
Next we'll look at the third arm of a strand: