git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/tutorials/gall/state.udon
123 lines 4.1 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'2'
5 title/'State'
6 ==
7;>
9# State
11In the last section we built a few small apps that sent moves. These apps were
12entirely stateless, however. Most useful apps require some amount of state.
13Let's build a trivial stateful app. It'll keep a running the sum of all the
14atoms we poke it with. Here's `examples/app/sum.hoon`:
16```
17:: Keeps track of the sum of all the atoms it has been
18:: poked with and prints the sum out
19::
20:::: /===/app/sum/hoon
21 ::
22!:
23|%
24+$ move [bone card]
25+$ card $% $~
26 ==
27--
28|_ [bow=bowl:gall sum=@]
29::
30++ poke-atom
31 |= tom=@
32 ^- [(list move) _+>.$]
33 ~& sum+(add sum tom)
34 [~ +>.$(sum (add sum tom))]
35::
36++ coup
37 |= [wir=wire err=(unit tang)]
38 ^- [(list move) _+>.$]
39 ?~ err
40 ~& sum+success+'Poke succeeded!'
41 [~ +>.$]
42 ~& sum+error+'Poke failed. Error:'
43 ~& sum+error+err
44 [~ +>.$]
45::
46--
47```
49We can start it with `|start %sum`, and then run it:
51```
52~fintud-macrep:dojo> :sum &atom 5
53[%sum 5]
54>=
56~fintud-macrep:dojo> :sum &atom 2
57[%sum 7]
58>=
60~fintud-macrep:dojo> :sum &atom 15
61[%sum 22]
62>=
63```
65We can see that app state is being saved, but when, where, and how?
67The state is stored as the second thing in the `|_` line. In our case, it's
68simply an atom named `sum`. We change it by producing our state not with
69`+>.$` (as before), but with `+>.$(sum (add sum tom))`. We've seen all these
70parts before, but you might not recognize them.
72Recall in the first chapter that we recursed with the expression
73`$(b (add 3 b))`. This meant "produce `$` with `b` changed to `(add 3 b)`.
74Similarly, `+>.$(sum (add sum tom))` means "produce `+>.$` (i.e. our
75context, which contains our state) with `sum` changed to `(add sum tom)`.
77At a high level, then, when we handle state, we do it explicitly. It's passed in
78and produced explicitly. In Unix systems, application state is just a block of
79memory, which you need to serialize to disk if you want to keep it around for
80very long.
82In Urbit, app state is a single (usually complex) value. In our example, we have
83very simple state, so we defined `sum=@`, meaning that our state is an atom.
84Of course, `sum` is just a name, and you're free to name your state whatever
85you like. But let's clarify a couple other things before we continue.
87First, `bowl` is a set of general global states. This set is managed by the
88system. It includes things like `now` (the current time), `our` (our urbit
89identity), and `eny` (512 bits of guaranteed-fresh entropy). For the full list
90of things in `++bowl`, search for `++ bowl` (note: two spaces) in
91`/arvo/zuse.hoon`.
93> This is, perhaps, the most common way to learn Hoon. The easiest way to learn about an identifier you see in code is to search in `/arvo/zuse.hoon` and `/arvo/hoon.hoon` for it.\\ Urbit's codebase is less than 30000 lines of code combined, including the hoon parser, the compiler, and the `/arvo` microkernel, so you can usually use the code and its comments as a reference doc. You can also read [zuse.hoon](https://github.com/urbit/arvo/blob/master/arvo/zuse.hoon) and [hoon.hoon](https://github.com/urbit/arvo/blob/master/arvo/hoon.hoon) in your browser.
95The second thing we should clear up is this: Urbit needs no "serialize to disk"
96step. Everything you produce in the app state is persistent across calls to the
97app, restarts of the urbit, and even power failure. If you want to write to the
98Unix filesystem, you can, but it's not needed for persistence. Urbit has
99transactional events, which makes it an [ACID operating
100system](https://en.wikipedia.org/wiki/ACID). Thus, you don't have to worry about
101persistence when programming in Urbit, or ever go through the hassle of having
102to set up and write to a database.
104*Exercises*:
106- Modify `:sum` to reset the counter when you poke it with 0.
108- Write an app called `last` that prints out the previous value you poked it with.
110Sample output:
112```
113~fintud-macrep:dojo> :last 7
114[%last 0]
115>=
117~fintud-macrep:dojo> :last [1 2 3]
118[%last 7]
119>=
121~fintud-macrep:dojo> :last 'howdy'
122[%last [1 2 3]]
123```