Managing Shared State
In this pack:
sizing,
notation,
rule strictness.
Overview
Some state is reached by more than one thread or task at once. This skill
keeps such state safe in three ways: it shares values that never change,
confines changing state to one owner, and guards the rest with a lock. It
adds the handoff that keeps a half-built object from another thread, the
written policy a review can check, and the choice between a monitor
object and an active object. The result is state that loses no change,
and a caller that does not wait behind another's slow call.
When to use
- Several threads or tasks read and change one object at once.
- A counter, cache or collection loses changes when the load rises.
- A constructor hands its object to another thread or a shared field.
- More than one thread reaches a class's fields, and no note says how
they are kept safe.
- A lock is about to be added, or one piece of state needs one owner.
- A choice between a monitor object and an active object is due.
When not to use
- Two requests or processes change the state through the store, such as
two receptionists saving one appointment. That is
designing aggregates.
- The question is which thread may touch a screen. That is rule 6 of
separating presentation from domain.
- No object is reached by more than one thread or task, such as a
service whose requests share nothing but the store.
- The question is retrying or timing out a call to another system. That
is making work reliable, which
chooses the timeout and when a retry is safe.
Core rules
Default. Share immutable values between threads and tasks. A value
whose fields never change can be read by any number of them at once
with no lock, as rule 2 of
modeling values and entities
makes every value. A change builds a new value and puts it in place of
the old one whole.
The exception is state that changes so often that building a new value
each time costs too much, such as a count of arrivals: confine it, as
rule 2 says, or guard it, as rule 5 says.
Rule. Confine each piece of changing state to one owner. One
thread, one task or one request reads and writes it, and any other
part asks the owner by a message. State only its owner touches needs
no lock. The objects one request loads, such as the appointment a use
case changes, belong to that request alone; changes between requests
meet in the store, where
designing aggregates checks a
version and refuses the second of two saves made from stale copies.
Rule. Hand an object to another thread only when it is complete, and
only through a handoff the language makes safe. Such a handoff is a
queue built for threads, a field written and read under one lock, or a
reference the language publishes whole. Never let a constructor hand
out the object it is building, and never put a half-built object in a
shared field. Another thread can otherwise see fields the constructor
has not set. Rule 1 of
constructing valid objects
makes an object complete when its constructor ends; this rule keeps
any other thread from seeing it sooner.
Rule. Write down the synchronisation policy of every class whose
changing state more than one thread reaches. Say which fields are
shared, which lock or owner guards each, and which methods must hold
it, beside the class where its readers see it. Without that note a
review cannot check the class, and the next change breaks it unseen.
Rule. Make a check and the change it guards one step. The object
that holds the state checks it and changes it inside one method, under
one lock held for the whole method, so no other thread changes the
state in between. A caller never checks in one message and changes in
another: a slot found free in one message and reserved in the next can
be reserved twice in between. Rule 3 of
encapsulating state and behaviour
already tells the object rather than asking it; under threads, asking
first is also a race.
Judgement. Choose between a monitor object and an active object. A
monitor object holds its state and one lock, and each caller waits
while one of its methods runs. An active object owns its state on a
thread or task of its own, takes requests from a queue, and answers
each with a reply the caller collects later. What tips the balance is
how long the work under the lock takes and whether callers can wait: a
short check and change suits a monitor, while slow work, such as a
call to another system, suits an active object, so no caller waits
behind another's slow call. Never call another system or another
locked object while holding a monitor's lock. Which thread may touch a
screen is rule 6 of
separating presentation from domain;
that choice belongs there, not here.
Pattern
Before, FreeTimesCache holds one clinician's free times today for
request threads to read, while a background job refreshes it in place.
After, the free times are a FreeTimes value that never changes, and the
cache holds the current one and replaces it whole.
Before:
class FreeTimesCache
- times: List<DateTime>
+ new()
times := new List<DateTime>()
+ refresh(fresh: List<DateTime>): void
times.clear()
times.addAll(fresh)
+ freeTimes(): List<DateTime>
return times.copy()
clear and addAll are taken to empty the list and to add each time in
turn, so a request that reads between them sees an empty day, and a copy
taken while addAll runs reads a list another thread is changing.
After:
value FreeTimes
- times: List<DateTime>
+ new(given: List<DateTime>)
times := given.copy()
+ all(): ReadOnlyList<DateTime>
return times.readOnlyView()
class FreeTimesCache
-- current is shared, replaced whole and never changed in place, so no
-- lock guards it
- current: FreeTimes
+ new(initial: FreeTimes)
current := initial
+ refresh(fresh: FreeTimes): void
current := fresh
+ freeTimes(): ReadOnlyList<DateTime>
return current.all()
current := fresh is taken to publish the new FreeTimes to every thread
whole, through the language's own construct for a reference threads
share; this skill names no language. A reader gets the old day or the new
one, never a mixture. The background job builds each FreeTimes before
it sends refresh. ReadOnlyList is the notation's. Nothing is stored:
the cache lives in memory and no transaction is opened. Each version
answers one clinician's free times, and only refresh changes the cache.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A field that more than one thread changes, with no written policy
beside its class.
- A check in one message and the change it guards in another.
- A collection rebuilt in place while other threads read it.
- A constructor that hands its object to another thread or a shared
field.
- A lock held while calling another system or another locked object.
- A value object with a field that can change.
Common mistakes
- Adding a lock to every method of a class that no other thread reaches.
- Making each field safe on its own while a rule spans two of them.
- Handing an entity one request loaded to another request instead of
loading it again.
- Guarding with a lock in memory what two processes change through the
store.
- Waiting for an active object's reply on the active object's own thread.
Related skills
Further reading
- Confinement and handoff
- Monitors and active objects
1---2name: oo-managing-shared-state3description: Use when several threads or tasks use one object at once, when a cache or counter goes wrong under load, or when choosing locks or one owner.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-managing-shared-state7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Managing Shared State1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920Some state is reached by more than one thread or task at once. This skill21keeps such state safe in three ways: it shares values that never change,22confines changing state to one owner, and guards the rest with a lock. It23adds the handoff that keeps a half-built object from another thread, the24written policy a review can check, and the choice between a monitor25object and an active object. The result is state that loses no change,26and a caller that does not wait behind another's slow call.2728## When to use2930- Several threads or tasks read and change one object at once.31- A counter, cache or collection loses changes when the load rises.32- A constructor hands its object to another thread or a shared field.33- More than one thread reaches a class's fields, and no note says how34 they are kept safe.35- A lock is about to be added, or one piece of state needs one owner.36- A choice between a monitor object and an active object is due.3738## When not to use3940- Two requests or processes change the state through the store, such as41 two receptionists saving one appointment. That is42 [designing aggregates](../oo-designing-aggregates/SKILL.md).43- The question is which thread may touch a screen. That is rule 6 of44 [separating presentation from domain](../oo-separating-presentation-from-domain/SKILL.md).45- No object is reached by more than one thread or task, such as a46 service whose requests share nothing but the store.47- The question is retrying or timing out a call to another system. That48 is [making work reliable](../oo-making-work-reliable/SKILL.md), which49 chooses the timeout and when a retry is safe.5051## Core rules52531. Default. **Share immutable values between threads and tasks.** A value54 whose fields never change can be read by any number of them at once55 with no lock, as rule 2 of56 [modeling values and entities](../oo-modeling-values-and-entities/SKILL.md)57 makes every value. A change builds a new value and puts it in place of58 the old one whole.5960 The exception is state that changes so often that building a new value61 each time costs too much, such as a count of arrivals: confine it, as62 rule 2 says, or guard it, as rule 5 says.63642. Rule. **Confine each piece of changing state to one owner.** One65 thread, one task or one request reads and writes it, and any other66 part asks the owner by a message. State only its owner touches needs67 no lock. The objects one request loads, such as the appointment a use68 case changes, belong to that request alone; changes between requests69 meet in the store, where70 [designing aggregates](../oo-designing-aggregates/SKILL.md) checks a71 version and refuses the second of two saves made from stale copies.72733. Rule. **Hand an object to another thread only when it is complete, and74 only through a handoff the language makes safe.** Such a handoff is a75 queue built for threads, a field written and read under one lock, or a76 reference the language publishes whole. Never let a constructor hand77 out the object it is building, and never put a half-built object in a78 shared field. Another thread can otherwise see fields the constructor79 has not set. Rule 1 of80 [constructing valid objects](../oo-constructing-valid-objects/SKILL.md)81 makes an object complete when its constructor ends; this rule keeps82 any other thread from seeing it sooner.83844. Rule. **Write down the synchronisation policy of every class whose85 changing state more than one thread reaches.** Say which fields are86 shared, which lock or owner guards each, and which methods must hold87 it, beside the class where its readers see it. Without that note a88 review cannot check the class, and the next change breaks it unseen.89905. Rule. **Make a check and the change it guards one step.** The object91 that holds the state checks it and changes it inside one method, under92 one lock held for the whole method, so no other thread changes the93 state in between. A caller never checks in one message and changes in94 another: a slot found free in one message and reserved in the next can95 be reserved twice in between. Rule 3 of96 [encapsulating state and behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)97 already tells the object rather than asking it; under threads, asking98 first is also a race.991006. Judgement. **Choose between a monitor object and an active object.** A101 monitor object holds its state and one lock, and each caller waits102 while one of its methods runs. An active object owns its state on a103 thread or task of its own, takes requests from a queue, and answers104 each with a reply the caller collects later. What tips the balance is105 how long the work under the lock takes and whether callers can wait: a106 short check and change suits a monitor, while slow work, such as a107 call to another system, suits an active object, so no caller waits108 behind another's slow call. Never call another system or another109 locked object while holding a monitor's lock. Which thread may touch a110 screen is rule 6 of111 [separating presentation from domain](../oo-separating-presentation-from-domain/SKILL.md);112 that choice belongs there, not here.113114## Pattern115116Before, `FreeTimesCache` holds one clinician's free times today for117request threads to read, while a background job refreshes it in place.118After, the free times are a `FreeTimes` value that never changes, and the119cache holds the current one and replaces it whole.120121Before:122123```text124class FreeTimesCache125 - times: List<DateTime>126 + new()127 times := new List<DateTime>()128 + refresh(fresh: List<DateTime>): void129 times.clear()130 times.addAll(fresh)131 + freeTimes(): List<DateTime>132 return times.copy()133```134135`clear` and `addAll` are taken to empty the list and to add each time in136turn, so a request that reads between them sees an empty day, and a copy137taken while `addAll` runs reads a list another thread is changing.138139After:140141```text142value FreeTimes143 - times: List<DateTime>144 + new(given: List<DateTime>)145 times := given.copy()146 + all(): ReadOnlyList<DateTime>147 return times.readOnlyView()148149class FreeTimesCache150 -- current is shared, replaced whole and never changed in place, so no151 -- lock guards it152 - current: FreeTimes153 + new(initial: FreeTimes)154 current := initial155 + refresh(fresh: FreeTimes): void156 current := fresh157 + freeTimes(): ReadOnlyList<DateTime>158 return current.all()159```160161`current := fresh` is taken to publish the new `FreeTimes` to every thread162whole, through the language's own construct for a reference threads163share; this skill names no language. A reader gets the old day or the new164one, never a mixture. The background job builds each `FreeTimes` before165it sends `refresh`. `ReadOnlyList` is the notation's. Nothing is stored:166the cache lives in memory and no transaction is opened. Each version167answers one clinician's free times, and only `refresh` changes the cache.168169## Red flags170171Places to look, not verdicts. A red flag becomes a finding only with172evidence: a measurement, a reproducible bug, or a failing test.173174- A field that more than one thread changes, with no written policy175 beside its class.176- A check in one message and the change it guards in another.177- A collection rebuilt in place while other threads read it.178- A constructor that hands its object to another thread or a shared179 field.180- A lock held while calling another system or another locked object.181- A value object with a field that can change.182183## Common mistakes184185- Adding a lock to every method of a class that no other thread reaches.186- Making each field safe on its own while a rule spans two of them.187- Handing an entity one request loaded to another request instead of188 loading it again.189- Guarding with a lock in memory what two processes change through the190 store.191- Waiting for an active object's reply on the active object's own thread.192193## Related skills194195- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule196 labels.197- [oo-modeling-values-and-entities](../oo-modeling-values-and-entities/SKILL.md)198 makes a value immutable, so no holder sees another's change.199- [oo-constructing-valid-objects](../oo-constructing-valid-objects/SKILL.md)200 makes an object complete when its constructor ends.201- [oo-encapsulating-state-and-behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)202 tells the object what to do rather than asking for its state.203- [oo-designing-aggregates](../oo-designing-aggregates/SKILL.md) checks a204 version and refuses a save made from a stale copy.205- [oo-separating-presentation-from-domain](../oo-separating-presentation-from-domain/SKILL.md)206 decides which thread may touch a screen.207208## Further reading209210- [Confinement and handoff](references/confinement-and-handoff.md)211- [Monitors and active objects](references/monitors-and-active-objects.md)