git.iko.soy/urbit.org
on 932d391 help sign in
urbit.org/docs/programming/system/state.md
109 lines 3.7 kB history raw
1---
2next: true
3sort: 4
4title: State
5---
7In the last section we built a few small apps that sent moves.
8These apps were entirely stateless, however. Most useful apps
9require some amount of state. Let's build a trivial stateful
10app. It'll keep a running the sum of all the atoms we poke it with.
11Here's `app/sum.hoon`:
13```
14/? 314
15!:
16|_ {bowl state/@}
17++ poke-atom
18 |= arg/@
19 ^- {(list) _+>.$}
20 ?: =(arg 0)
21 [~ +>.$(state 0)]
22 ~& [%so-far (add state arg)]
23 [~ +>.$(state (add state arg))]
24--
25```
27We can start it with `|start %sum`, and then run it:
29```
30~fintud-macrep:dojo> :sum &atom 5
31[%so-far 5]
32>=
33~fintud-macrep:dojo> :sum &atom 2
34[%so-far 7]
35>=
36~fintud-macrep:dojo> :sum &atom 15
37[%so-far 22]
38>=
39```
41We can see that app state is being saved, but when, where, and
42how?
44The state is stored as the second thing in the `|_` line. In our
45case, it's simply an atom named `state`. We change it by
46producing as our state not with `+>.$` (as before), but with `+>.$(state (add state arg))`. We've seen all these parts before, but you might not
47recognize them.
49Recall in the first chapter that we recursed with the expression
50`$(b (add 3 b))`. This meant "produce `$` with `b` changed to
51`(add 3 b)`. Similarly, `+>.$(state (add state arg))` means
52"produce `+>.$` (i.e. our context, which contains our state) with
53`state` changed to `(add state arg)`.
55At a high level, then, when we handle state, we do it explicitly.
56It's passed in and produced explicitly. In Unix systems,
57application state is just a block of memory, which you need to
58serialize to disk if you want to keep it around for very long.
60In urbit, app state is a single (usually complex) value. In our
61example, we have very simple state, so we defined `state=@`,
62meaning that our state is an atom. Of course, `state` is just a
63name we're assigning to it, and you're free to use whatever name
64you want.
66There are at least two points you may be wondering about. First, `bowl` is a set of general global state that is managed by the system. It
67includes things like `now` (current time), `our` (our urbit
68identity), and `eny` (256 bits of guaranteed-fresh entropy). For
69the full list of things in `++bowl`, search for `++ bowl` (note
70the double space) in `/arvo/zuse.hoon`.
72<blockquote class="blockquote">
73This is a very common technique in learning hoon. While
74documentation exists, often the easiest way to learn about an
75identifier you see in code is to search in `/arvo/zuse.hoon`
76and `/arvo/hoon.hoon` for it. These are our two "standard
77libraries", and they're usually not hard to read. Since
78urbit's codebase is relatively small (those two files are less
79than 15000 lines of code combined, and besides the standard
80library they include the hoon parser and compiler, plus the
81/arvo microkernel), you can usually use the code and the
82comments as reference doc.
83</blockquote>
85The second thing is that urbit needs no "serialize to disk" step.
86Everything you produce in the app state is persistent across
87calls to the app, restarts of the urbit, and even power failure.
88If you want to write to the filesystem, you can, but it's not
89needed for persistence. Urbit has transactional events, which
90makes it an [ACID operating system](https://en.wikipedia.org/wiki/ACID). Thus, you don't have to
91worry about persistence when programming in urbit or to ever go
92through the hassle of having to set up and write to a database.
94**Exercises**:
96- Modify `:sum` to reset the counter when you poke it with zero.
98- Write an app that prints out the previous value you poked it
99 with. Sample output:
101```
102~fintud-macrep:dojo> :last 7
103[%last 0]
104>=
105~fintud-macrep:dojo> :last [1 2 3]
106[%last 7]
107>=
108~fintud-macrep:dojo> :last 'howdy'
109[%last [1 2 3]]