Guide for Unified Succession Model

[stuarthalloway]

We talk about Clojure's Unified Succession Model when explaining the various reference types, but it is not mentioned on the site. This SO answer might be a good starting point.

At this point I strongly prefer "succession" over "update". "Succession" is more precise, and not polluted by the "in place" connotations of "update".

[puredanger]

Would also be good to reference:

• https://clojure.org/reference/atoms
• https://clojure.org/reference/refs
• https://clojure.org/reference/agents
• https://clojure.org/reference/vars

[jafingerhut]

I am out of the loop, obviously, but in what possible way is 'succession' different than an 'in place update', with all of the connotations of 'in place' included?

[puredanger]

Succession implies that one thing follows from the prior value, rather than modify or replace the prior. In particular, Clojure's succession model separates the values from the identity holding the current value whereas (for example) a Java field is both the identity and the "place" that is modified.

[vvvvalvalval]

So I'm willing to take a stab at this, but I may need help defining what problem of understanding we're trying to solve for the reader of the guide here (I'm afraid I'm now so familiar with the USM that it seems obvious to me now).

We also need to clarify what the guide should add compared to the existing page on State and Identity.

---

TL;DR How to help

• Suggest links to related resources: currently I have the page about state, this SO answer, Rich Hickey's Are We There Yet? and Persistent Data Structures and Managed References.
• Give me inputs about what the guide needs to clarify (see below).

---

Presumably, this is more about the Succession Model than about it being Unified: we can't be content with just saying that all ref types in Clojure (and some outside Clojure, I'm looking at you Datomic connections and Git branches) have equivalent APIs, that's not worth a while guide (right?).

So what is it about the Succession Model that the reader may be struggling with? I see a number of possibilities:

• Shifting from an 'absolute change' to a 'relative/incremental change' mindset. Absolute says "I will be the one setting the next value" (which requires locking in concurrent settings), whereas Relative says 'I want a change in that direction in the future'. Absolute means the values are the source of truth, whereas Relative means the patches are the source of truth and values derived from them.
• Decomposing the notion of 'change over time' into Identity, State and Values. I expect these distinctions to be obliterated by a mutable/imperative background.
• More philosophically, we may need to draw the distinction 'Imperativeness is good at simulating how the world works' (arguably, from a physics standpoint, the world is a huge mutable data structure, and we can't really perceive its parts coherently, nor are there natural Identities in there) versus 'The Unified Succession Model is good at modeling how we perceive and reason about the world' (Our perception of something is an immutable snapshot residing in our mind, and Identities are artificial abstractions we superimpose on top of this sequence of snapshots). That may be a good angle for motivating the guide. (However, I'm really starting to put words in the mouths of the designers of that Unified Succession Model here. Maybe @richhickey will want to tell us if this is in line with the original spirit of the Unified Succession Model, and the work of A.N. Whitehead from which it was inspired?)
• Answering the very down-to-earth if things can't change, where do I put the state? question. But I'm not sure this warrants introducing the USM - it is sufficient to answer 'just put it in a ref'.
• BUT, the above question may lead to why can't we model change only with values? (e.g with monadic values as seen in pure functional languages and FRP systems). So we need to motivate the addition of managed references on top of values. One possible answer is 'so that Identities can be reified', but that's a bit of a circular argument, since the motivation for reified Identities remains to be explained. In my view, a more concrete way to see it is programmability: since our programs are often evolving pieces of states, making programs programmable means that we need to represent 'evolving pieces of states' as first-class programmatic objects. Maybe an endogenous/exogenous analogy could help here.

Those are very broad strokes, but I'd like some validation before pushing further.

[puredanger]

There are three kinds of things on the site:

• about/rationale/big ideas - I think this is covered by State and Identity and I would not expect anyone but Rich to extend this area really
• reference - covered now by https://clojure.org/reference/vars, https://clojure.org/reference/refs, https://clojure.org/reference/agents, and https://clojure.org/reference/atoms. It may be useful to make a new reference page that unifies these. I think the best expression of these together is in Programming Clojure, written by Stu and later lightly updated by me in 3rd edition. That's all copyrighted so can't lift directly, but I think that's a guide to how to contextualize these existing pages.
• guides - how-to, practical tutorial-esque advice to a topic. Some of the things mentioned here would be useful as a guide. Like how to model state, how to choose which of the reference types to use, things to consider, etc.

[vvvvalvalval]

I should probably mention that I no longer have the availability for this sort of contribution :)

[puredanger]

No worries, thanks!