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

4
// =============================================================================
5
// 39c - Latch: Barrier Synchronization
6
// =============================================================================
7
//
8
// Latch.make(open?)   create a gate (default closed)  — Effect<Latch>
9
// latch.await               block until the latch is open   — Effect<void>
10
// latch.open                open the gate, releasing waiters — Effect<void>
11
// latch.close               close the gate for the next wave — Effect<void>
12
// latch.whenOpen(effect)    run effect only when open       — Effect<A>
13
//
14
// A Latch is a reusable gate: close it to hold fibers, open it to release them.
15
// Unlike Deferred, a Latch carries no value — it is purely a signal.
16
// Unlike Deferred, a Latch can be closed again after opening for a second wave.
17

18
describe("39c - Latch", () => {
19
  // @beat
20
  //   id: open-and-await
21
  //   shape: one-todo
22
  //   title: Create a closed latch and open it
23
  //   teaches: Latch.make(false) starts closed; latch.await suspends; latch.open unblocks all waiters.
24
  //   hint: yield* Latch.make(false), fork a fiber that does latch.await, then yield* latch.open
25
  describe("Latch.make and latch.open", () => {
26
    it("open releases a fiber blocked on await", async () => {
27
      //      ┌─── Effect<void>
28
      //      ▼
29
      const program = /* @stub */ Effect.gen(function* () {
30
        const latch = yield* Latch.make(false)
31

32
        const waiter = yield* Effect.forkChild(latch.await)
33

34
        yield* latch.open
35

36
        yield* Fiber.join(waiter)
37
      }) /* @end */
38

39
      await expect(Effect.runPromise(program)).resolves.toBeUndefined()
40
    })
41

42
    it("already-open latch does not block", async () => {
43
      const program = Effect.gen(function* () {
44
        const latch = yield* Latch.make(true) // starts open
45
        yield* latch.await // returns immediately
46
        return "passed"
47
      })
48

49
      expect(await Effect.runPromise(program)).toBe("passed")
50
    })
51
  })
52
  // @end-beat
53

54
  // @beat
55
  //   id: multiple-waiters
56
  //   shape: one-todo
57
  //   title: Release N fibers simultaneously
58
  //   teaches: All fibers suspended on latch.await are released at once when latch.open is called — a single signal fans out to every waiter.
59
  //   hint: fork N waiters before opening; join all after — they all resume from the same open signal
60
  describe("multiple waiters", () => {
61
    it("releases all suspended fibers when opened", async () => {
62
      const program = Effect.gen(function* () {
63
        const latch = yield* Latch.make(false)
64
        const log: number[] = []
65

66
        // Fork three fibers — all block on latch.await.
67
        const fibers = yield* Effect.all(
68
          [1, 2, 3].map((n) =>
69
            Effect.forkChild(
70
              latch.await.pipe(Effect.andThen(Effect.sync(() => log.push(n)))),
71
            ),
72
          ),
73
        )
74

75
        // Open the gate — all three are released simultaneously.
76
        yield* latch.open
77
        yield* Effect.all(fibers.map(Fiber.join))
78

79
        return log.sort()
80
      })
81

82
      // Predict the sorted log after all three waiters resume.
83
      expect(await Effect.runPromise(program)).toEqual(/* @stub */ [1, 2, 3] /* @end */)
84
    })
85
  })
86
  // @end-beat
87

88
  // @beat
89
  //   id: close-and-reuse
90
  //   shape: one-todo
91
  //   title: Close and reuse the latch for a second wave
92
  //   teaches: latch.close resets the gate so later fibers block again — a Latch is reusable across multiple open/close cycles, unlike Deferred which completes exactly once.
93
  //   hint: yield* latch.close after the first wave completes, then open again for the second wave
94
  describe("latch.close — reuse for a second wave", () => {
95
    it("blocks a second wave after close, releases on second open", async () => {
96
      const program = /* @stub */ Effect.gen(function* () {
97
        const latch = yield* Latch.make(false)
98
        const log: string[] = []
99

100
        // Wave 1
101
        const w1 = yield* Effect.forkChild(
102
          latch.await.pipe(Effect.andThen(Effect.sync(() => log.push("wave-1")))),
103
        )
104
        yield* latch.open
105
        yield* Fiber.join(w1)
106

107
        // Close for wave 2
108
        yield* latch.close
109

110
        // Wave 2
111
        const w2 = yield* Effect.forkChild(
112
          latch.await.pipe(Effect.andThen(Effect.sync(() => log.push("wave-2")))),
113
        )
114
        yield* latch.open
115
        yield* Fiber.join(w2)
116

117
        return log
118
      }) /* @end */
119

120
      expect(await Effect.runPromise(program)).toEqual(["wave-1", "wave-2"])
121
    })
122
  })
123
  // @end-beat
124

125
  // @beat
126
  //   id: when-open
127
  //   shape: one-todo
128
  //   title: Run an effect only when the latch is open
129
  //   teaches: latch.whenOpen(effect) suspends until open, then immediately runs effect — shorter than await then flatMap when the pattern is repeated.
130
  //   hint: predict the one entry the gated effect pushes into log after latch.open
131
  describe("latch.whenOpen", () => {
132
    it("runs the effect only after the latch opens", async () => {
133
      const program = Effect.gen(function* () {
134
        const latch = yield* Latch.make(false)
135
        const log: string[] = []
136

137
        const fiber = yield* Effect.forkChild(
138
          latch.whenOpen(Effect.sync(() => log.push("ran"))),
139
        )
140

141
        // The fiber is suspended — nothing has run yet.
142
        expect(log).toEqual([])
143

144
        yield* latch.open
145
        yield* Fiber.join(fiber)
146

147
        return log
148
      })
149

150
      // Predict the log after latch.open releases the whenOpen fiber
151
      expect(await Effect.runPromise(program)).toEqual(/* @stub */ ["ran"] /* @end */)
152
    })
153
  })
154
  // @end-beat
155
})