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