40 - SynchronizedRef: Effectful Atomic Updates

Previous · Next

A SynchronizedRef<A> is a Ref<A> whose update function may itself be an Effect. Concurrent effectful updates are serialized: each fiber’s (A) => Effect<A> runs to completion before the next one starts.

This is the primitive for “read state, do async work, write state” with no race window.

What you’ll work through

index.test.ts covers the race-motivation beat, then updateEffect for serialized effectful updates, then modifyEffect for read-decide-write in one step, and finishes with a composite cache-fill example where two concurrent loads cannot collide.

By the end you should be able to identify the “read state, do async work, write state” pattern at sight and pick SynchronizedRef over Ref only when the update body contains a yield*.

Notice. Serialization is not free. Use Ref whenever the update is pure — SynchronizedRef exists for the case where serialisation is the point.

Why `SynchronizedRef` exists

Ref.update works on a pure (A) => A transition — a compare-and-swap loop guarantees atomicity without locking. The moment your update body contains a yield* (a database lookup, an HTTP call, anything Effect- shaped), CAS no longer applies: between the read and the write another fiber could publish a new value, and your effectful update would clobber it.

SynchronizedRef is the locking variant — updateEffect accepts (A) => Effect<A> and serializes concurrent calls.

1
Ref             update: (A) => A                pure, lock-free atomic CAS
2
SynchronizedRef updateEffect: (A) => Effect<A>  serialized, one update at a time
3

4
Two fibers calling SynchronizedRef.updateEffect:
5

6
  fiber 1: read A0 ─▶ Effect<A1>             ─▶ write A1 ─┐
7
  fiber 2:                       wait ───────────────────▶ read A1 ─▶ Effect<A2> ─▶ write A2

Rule of thumb. Reach for SynchronizedRef when the update body contains a yield* and you need the read-write pair to span that yield atomically. For pure transitions, stay with Ref — it’s lock-free and faster.

Your turn read the test that uses a plain `Ref` with an effectful update and observe the lost-update bug. Then read the partner test that uses `SynchronizedRef.updateEffect` and confirm both fibers' work is preserved.

`SynchronizedRef.make` and `get`

make mirrors Ref.make. get is identical, reads do not need serialization.

1
import { Effect, SynchronizedRef } from "effect"
2

3
//      ┌─── Effect<SynchronizedRef<Map<string, number>>>
4
//      ▼
5
const makeCache = SynchronizedRef.make<Map<string, number>>(new Map())

`SynchronizedRef.updateEffect`

Applies an effectful update to the current value. While the update is running, every other updateEffect for the same ref is suspended.

1
//      ┌─── Effect<void, E, R>
2
//      ▼
3
const loadUser = (
4
  cache: SynchronizedRef.SynchronizedRef<Map<string, number>>,
5
  userId: string,
6
) =>
7
  SynchronizedRef.updateEffect(cache, (map) =>
8
    map.has(userId)
9
      ? Effect.succeed(map)
10
      : fetchScore(userId).pipe(
11
          Effect.map((score) => new Map(map).set(userId, score)),
12
        ),
13
  )

Details

The signature is (a: A) => Effect<A, E, R>. Failures propagate; the ref is left unchanged if the effect fails.

Interruption is observed at the next yield point.

When to Use

Cache fills, lazy initialization, transactional state updates that read a database, batch flushes, any update where computing the new value is itself an Effect.

`SynchronizedRef.modifyEffect`

The synchronized counterpart to Ref.modify. The function takes the current state and returns Effect<[B, A]> — B is the value the caller receives, A is the new state to commit.

Read and write happen atomically across the yield, so even an effectful body cannot race itself against another modifyEffect on the same ref.

1
import { Effect, SynchronizedRef } from "effect"
2

3
//      ┌─── Effect<string>
4
//      ▼
5
const dequeue = (ref: SynchronizedRef.SynchronizedRef<ReadonlyArray<string>>) =>
6
  SynchronizedRef.modifyEffect(ref, ([head, ...rest]) =>
7
    Effect.succeed([head, rest] as [string, ReadonlyArray<string>]),
8
  )
9

10
// More realistically — the new state computation itself does IO:
11
const dequeueWithAudit = (
12
  ref: SynchronizedRef.SynchronizedRef<ReadonlyArray<string>>,
13
) =>
14
  SynchronizedRef.modifyEffect(ref, ([head, ...rest]) =>
15
    Effect.gen(function* () {
16
      yield* auditService.recordDequeue(head)
17
      return [head, rest] as [string, ReadonlyArray<string>]
18
    }),
19
  )

Rule of thumb. Reach for modifyEffect when the new state depends on the result of an Effect and the caller needs the read value as well. For “just update” use updateEffect; for “just read” use get.

Your turn complete a `modifyEffect` body that pops the head of a list and returns it alongside the new tail. Run two concurrent dequeues and confirm every queued item is observed exactly once.

Composite Example: Atomic Cache Fill

1
//      ┌─── Effect<Map<string, number>>
2
//      ▼
3
const program = Effect.gen(function* () {
4
  const cache = yield* SynchronizedRef.make<Map<string, number>>(new Map())
5

6
  const fetchScore = (id: string) => Effect.succeed(id.length * 10)
7

8
  const load = (id: string) =>
9
    SynchronizedRef.updateEffect(cache, (map) =>
10
      map.has(id)
11
        ? Effect.succeed(map)
12
        : fetchScore(id).pipe(Effect.map((score) => new Map(map).set(id, score))),
13
    )
14

15
  yield* Effect.all([load("alice"), load("bob")], { concurrency: "unbounded" })
16

17
  return yield* SynchronizedRef.get(cache)
18
})

Two concurrent loads, two distinct keys, no race: the second update sees the result of the first.

Common Pitfalls

1, Reaching for SynchronizedRef when Ref would do. Serialization is not free. If the update is pure, Ref.update is faster and simpler.

2, Reading then updating outside the lock.

1
// Wrong, race window between get and set
2
const score = yield* db.lookup(userId)
3
yield* Ref.update(cache, (m) => new Map(m).set(userId, score))
4

5
// Right, fetch and update are one serialized step
6
yield* SynchronizedRef.updateEffect(cache, (m) =>
7
  m.has(userId) ? Effect.succeed(m) : db.lookup(userId).pipe(
8
    Effect.map((score) => new Map(m).set(userId, score)),
9
  ),
10
)

3, Returning a mutated input. As with Ref, return a new value. The serializer protects against concurrent fibers, not against you mutating in place.

The full test suite

The index.test.ts for this lesson, verbatim from steps/40-synchronized-ref/.

1
import { describe, it, expect } from "vite-plus/test"
2
import { Effect, Ref, SynchronizedRef } from "effect"
3

4
// =============================================================================
5
// 36 - SynchronizedRef: Effectful Atomic Updates
6
// =============================================================================
7
//
8
// SynchronizedRef.make           Effect<SynchronizedRef<A>>
9
// SynchronizedRef.get            Effect<A>
10
// SynchronizedRef.updateEffect   (A) => Effect<A>   serialized under concurrency
11
// SynchronizedRef.modifyEffect   (A) => Effect<[B, A]>
12

13
describe("36 - SynchronizedRef", () => {
14
  // @beat
15
  //   id: race-motivation
16
  //   shape: one-todo
17
  //   title: Why plain Ref races on read-then-write
18
  //   teaches: A plain Ref.get followed by Ref.set leaves a race window where concurrent fibers can lose writes.
19
  //   hint: list every possible final value — either both updates land, or one is lost
20
  describe("Plain Ref vs SynchronizedRef", () => {
21
    it("plain Ref allows a read-then-write race", async () => {
22
      const racy = await Effect.runPromise(
23
        Effect.gen(function* () {
24
          const ref = yield* Ref.make(0)
25
          const update = Effect.gen(function* () {
26
            const current = yield* Ref.get(ref)
27
            yield* Ref.set(ref, current + 10) // race window
28
          })
29
          yield* Effect.all([update, update], { concurrency: "unbounded" })
30
          return yield* Ref.get(ref)
31
        }),
32
      )
33
      // One of the two updates can be lost.
34
      // Predict the set of values racy can legally take (one update may be lost)
35
      expect(/* @stub */ [10, 20] /* @end */).toContain(racy)
36
    })
37
  })
38
  // @end-beat
39

40
  // @beat
41
  //   id: update-effect
42
  //   shape: one-todo
43
  //   title: Serialize effectful updates with updateEffect
44
  //   teaches: SynchronizedRef.updateEffect runs (A) => Effect<A> as one indivisible step under concurrency.
45
  //   hint: SynchronizedRef.updateEffect(ref, (n) => Effect.succeed(n + 10))
46
  describe("SynchronizedRef.updateEffect", () => {
47
    it("runs an Effect to compute the next value", async () => {
48
      const program = /* @stub */ Effect.gen(function* () {
49
        const ref = yield* SynchronizedRef.make(0)
50
        yield* SynchronizedRef.updateEffect(ref, (n) => Effect.succeed(n + 10))
51
        return yield* SynchronizedRef.get(ref)
52
      }) /* @end */
53

54
      expect(await Effect.runPromise(program)).toBe(10)
55
    })
56

57
    it("serializes concurrent updates — no lost writes", async () => {
58
      //      ┌─── Effect<ReadonlyArray<number>>
59
      //      ▼
60
      const program = /* @stub */ Effect.gen(function* () {
61
        const ref = yield* SynchronizedRef.make<ReadonlyArray<number>>([])
62
        const append = (n: number) =>
63
          SynchronizedRef.updateEffect(ref, (arr) => Effect.succeed([...arr, n]))
64

65
        yield* Effect.all([append(1), append(2), append(3)], {
66
          concurrency: "unbounded",
67
        })
68

69
        return yield* SynchronizedRef.get(ref)
70
      }) /* @end */
71

72
      const result = await Effect.runPromise(program)
73
      expect([...result].sort()).toEqual([1, 2, 3])
74
    })
75
  })
76
  // @end-beat
77

78
  // @beat
79
  //   id: modify-effect
80
  //   shape: worked-then-your-turn
81
  //   title: Return a value with modifyEffect
82
  //   teaches: SynchronizedRef.modifyEffect returns Effect<[B, A]> — B comes back to the caller, A is the new state.
83
  //   hint: SynchronizedRef.modifyEffect(ref, (n) => Effect.succeed([n, n * 2]))
84
  describe("SynchronizedRef.make and get", () => {
85
    it("reads back the initial value", async () => {
86
      const program = Effect.gen(function* () {
87
        const ref = yield* SynchronizedRef.make(0)
88
        return yield* SynchronizedRef.get(ref)
89
      })
90

91
      expect(await Effect.runPromise(program)).toBe(0)
92
    })
93
  })
94

95
  describe("SynchronizedRef.modifyEffect", () => {
96
    it("returns a value alongside the new state — atomically", async () => {
97
      const program = /* @stub */ Effect.gen(function* () {
98
        const ref = yield* SynchronizedRef.make(100)
99
        const old = yield* SynchronizedRef.modifyEffect(
100
          ref,
101
          (n) => Effect.succeed([n, n * 2]) as Effect.Effect<[number, number]>,
102
        )
103
        const current = yield* SynchronizedRef.get(ref)
104
        return { old, current }
105
      }) /* @end */
106

107
      const result = await Effect.runPromise(program)
108
      expect(result.old).toBe(100)
109
      expect(result.current).toBe(200)
110
    })
111
  })
112
  // @end-beat
113

114
  // @beat
115
  //   id: cache-fill
116
  //   shape: one-todo
117
  //   title: Atomic cache-fill pattern
118
  //   teaches: Using updateEffect for "check then fetch then store" eliminates the race window plain Ref leaves open.
119
  //   hint: wrap the whole read-fetch-write inside one SynchronizedRef.updateEffect
120
  describe("Effectful cache fill", () => {
121
    it("SynchronizedRef closes the race window plain Ref leaves open", async () => {
122
      // SynchronizedRef: read and write are one serialized step.
123
      const safe = await Effect.runPromise(
124
        /* @stub */ Effect.gen(function* () {
125
          const ref = yield* SynchronizedRef.make(0)
126
          const update = SynchronizedRef.updateEffect(ref, (n) => Effect.succeed(n + 10))
127
          yield* Effect.all([update, update], { concurrency: "unbounded" })
128
          return yield* SynchronizedRef.get(ref)
129
        }) /* @end */,
130
      )
131
      expect(safe).toBe(20)
132
    })
133
  })
134
  // @end-beat
135
})

07·02SynchronizedRef

40 - SynchronizedRef: Effectful Atomic Updates

What you’ll work through

Why `SynchronizedRef` exists

`SynchronizedRef.make` and `get`

`SynchronizedRef.updateEffect`

`SynchronizedRef.modifyEffect`

Composite Example: Atomic Cache Fill

Common Pitfalls

See Also

The full test suite

07·02SynchronizedRef

40 - SynchronizedRef: Effectful Atomic Updates

What you’ll work through

Why SynchronizedRef exists

SynchronizedRef.make and get

SynchronizedRef.updateEffect

SynchronizedRef.modifyEffect

Composite Example: Atomic Cache Fill

Common Pitfalls

See Also

The full test suite

Why `SynchronizedRef` exists

`SynchronizedRef.make` and `get`

`SynchronizedRef.updateEffect`

`SynchronizedRef.modifyEffect`