git.iko.soy/urbit.org
on 65048fe help sign in
urbit.org/docs/programming/system/state.md
107 lines 3.7 kB history raw
1---
2next: true
3sort: 3
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 `ape/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> This is a very common technique in learning hoon. While
73> documentation exists, often the easiest way to learn about an
74> identifier you see in code is to search in `/arvo/zuse.hoon`
75> and `/arvo/hoon.hoon` for it. These are our two "standard
76> libraries", and they're usually not hard to read. Since
77> urbit's codebase is relatively small (those two files are less
78> than 15000 lines of code combined, and besides the standard
79> library they include the hoon parser and compiler, plus the
80> /arvo microkernel), you can usually use the code and the
81> comments as reference doc.
83The second thing is that urbit needs no "serialize to disk" step.
84Everything you produce in the app state is persistent across
85calls to the app, restarts of the urbit, and even power failure.
86If you want to write to the filesystem, you can, but it's not
87needed for persistence. Urbit has transactional events, which
88makes it an [ACID operating system](https://en.wikipedia.org/wiki/ACID). Thus, you don't have to
89worry about persistence when programming in urbit or to ever go
90through the hassle of having to set up and write to a database.
92**Exercises**:
94- Modify `:sum` to reset the counter when you poke it with zero.
96- Write an app that prints out the previous value you poked it
97 with. Sample output:
99```
100~fintud-macrep:dojo> :last 7
101[%last 0]
102>=
103~fintud-macrep:dojo> :last [1 2 3]
104[%last 7]
105>=
106~fintud-macrep:dojo> :last 'howdy'
107[%last [1 2 3]]