git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/programming/system/state.md
107 lines 3.6 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 ~& [%so-far (add state arg)]
21 [~ +>.$(state (add state arg))]
22--
23```
25We can start it with `|start %sum`, and then run it:
27```
28~fintud-macrep:dojo> :sum &atom 5
29[%so-far 5]
30>=
31~fintud-macrep:dojo> :sum &atom 2
32[%so-far 7]
33>=
34~fintud-macrep:dojo> :sum &atom 15
35[%so-far 22]
36>=
37```
39We can see that app state is being saved, but when, where, and
40how?
42The state is stored as the second thing in the `|_` line. In our
43case, it's simply an atom named `state`. We change it by
44producing as our state not with (as before) `+>.$` but `+>.$(state (add state
45arg))`. We've seen all these parts before, but you might not
46recognize them.
48Recall in the first chapter that we recursed with the expression
49`$(b (add 3 b))`. This meant "produce `$` with `b` changed to
50`(add 3 b)`. Similarly, `+>.$(state (add state arg))` means
51"produce `+>.$` (i.e. our context, which contains our state) with
52`state` changed to `(add state arg)`.
54At a high level, then, when we handle state, we do it explicitly.
55It's passed in and produced explicitly. In Unix systems,
56application state is just a block of memory, which you need to
57serialize to disk if you want to keep it around for very long.
59In urbit, app state is a single (usually complex) value. In our
60example, we have very simple state, so we defined `state=@`,
61meaning that our state is an atom. Of course, `state` is just a
62name we're assigning to it, and you're free to use whatever name
63you want.
65Two points you may be wondering about. Firstly, `bowl` is a set
66of 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 some
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 point 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](). 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]]