0
# Atomic Variables
1

2
Specialized support for waiting on atomic variable changes with built-in matchers and type-safe operations.
3

4
## Capabilities
5

6
### AtomicInteger Support
7

8
Wait for atomic integer values to meet specific conditions.
9

10
#### Matcher-Based Conditions
11

12
```java { .api }
13
/**
14
 * Wait until AtomicInteger value matches condition
15
 * @param atomic the AtomicInteger to monitor
16
 * @param matcher Hamcrest matcher for the integer value
17
 * @return final integer value when condition is met
18
 */
19
Integer untilAtomic(AtomicInteger atomic, Matcher<? super Integer> matcher);
20
```
21

22
#### Consumer-Based Assertions
23

24
```java { .api }
25
/**
26
 * Wait until AtomicInteger value passes consumer assertion
27
 * @param atomic the AtomicInteger to monitor
28
 * @param matcher consumer that performs assertions on the value
29
 */
30
void untilAtomic(AtomicInteger atomic, Consumer<? super Integer> matcher);
31
```
32

33
**AtomicInteger Examples:**
34
```java
35
AtomicInteger counter = new AtomicInteger(0);
36

37
// Wait for counter to reach threshold using matcher
38
Integer finalValue = await().untilAtomic(counter, greaterThanOrEqualTo(10));
39

40
// Wait for counter using multiple conditions
41
await().untilAtomic(counter, allOf(greaterThan(5), lessThan(20)));
42

43
// Wait using consumer assertion
44
await().untilAtomic(counter, value -> {
45
    assertThat(value).isGreaterThan(0);
46
    assertThat(value % 2).isEqualTo(0); // Even number
47
});
48

49
// Wait for specific value
50
await().untilAtomic(counter, equalTo(42));
51
```
52

53
### AtomicLong Support
54

55
Wait for atomic long values to meet specific conditions.
56

57
#### Matcher-Based Conditions
58

59
```java { .api }
60
/**
61
 * Wait until AtomicLong value matches condition
62
 * @param atomic the AtomicLong to monitor
63
 * @param matcher Hamcrest matcher for the long value
64
 * @return final long value when condition is met
65
 */
66
Long untilAtomic(AtomicLong atomic, Matcher<? super Long> matcher);
67
```
68

69
#### Consumer-Based Assertions
70

71
```java { .api }
72
/**
73
 * Wait until AtomicLong value passes consumer assertion
74
 * @param atomic the AtomicLong to monitor
75
 * @param matcher consumer that performs assertions on the value
76
 */
77
void untilAtomic(AtomicLong atomic, Consumer<? super Long> matcher);
78
```
79

80
**AtomicLong Examples:**
81
```java
82
AtomicLong timestamp = new AtomicLong(0);
83

84
// Wait for timestamp to be set
85
Long finalTimestamp = await().untilAtomic(timestamp, greaterThan(0L));
86

87
// Wait for timestamp to be recent
88
await().untilAtomic(timestamp, 
89
    greaterThan(System.currentTimeMillis() - Duration.ofMinutes(1).toMillis()));
90

91
// Wait using consumer assertion for complex validation
92
await().untilAtomic(timestamp, value -> {
93
    assertThat(value).isGreaterThan(startTime);
94
    assertThat(value).isLessThanOrEqualTo(System.currentTimeMillis());
95
});
96

97
// Wait for specific milestone
98
AtomicLong totalBytes = new AtomicLong(0);
99
await().atMost(30, SECONDS)
100
    .untilAtomic(totalBytes, greaterThanOrEqualTo(1_000_000L)); // 1MB
101
```
102

103
### AtomicBoolean Support
104

105
Wait for atomic boolean values and state changes.
106

107
#### Matcher-Based Conditions
108

109
```java { .api }
110
/**
111
 * Wait until AtomicBoolean value matches condition
112
 * @param atomic the AtomicBoolean to monitor
113
 * @param matcher Hamcrest matcher for the boolean value
114
 */
115
void untilAtomic(AtomicBoolean atomic, Matcher<? super Boolean> matcher);
116
```
117

118
#### Consumer-Based Assertions
119

120
```java { .api }
121
/**
122
 * Wait until AtomicBoolean value passes consumer assertion  
123
 * @param atomic the AtomicBoolean to monitor
124
 * @param matcher consumer that performs assertions on the value
125
 */
126
void untilAtomic(AtomicBoolean atomic, Consumer<? super Boolean> matcher);
127
```
128

129
#### Convenience Methods
130

131
```java { .api }
132
/**
133
 * Wait until AtomicBoolean becomes true
134
 * @param atomic the AtomicBoolean to monitor
135
 */
136
void untilTrue(AtomicBoolean atomic);
137

138
/**
139
 * Wait until AtomicBoolean becomes false
140
 * @param atomic the AtomicBoolean to monitor
141
 */
142
void untilFalse(AtomicBoolean atomic);
143
```
144

145
**AtomicBoolean Examples:**
146
```java
147
AtomicBoolean isReady = new AtomicBoolean(false);
148
AtomicBoolean isProcessing = new AtomicBoolean(true);
149

150
// Convenience methods for common cases
151
await().untilTrue(isReady);
152
await().untilFalse(isProcessing);
153

154
// Using matchers
155
await().untilAtomic(isReady, equalTo(true));
156
await().untilAtomic(isProcessing, equalTo(false));
157

158
// Using consumer assertions
159
await().untilAtomic(isReady, ready -> {
160
    assertThat(ready).isTrue();
161
    // Additional checks can be performed here
162
});
163

164
// Combined with timeout and polling
165
await().atMost(5, SECONDS)
166
    .pollInterval(100, MILLISECONDS)
167
    .untilTrue(systemInitialized);
168
```
169

170
### AtomicReference Support
171

172
Wait for atomic reference values and object state changes.
173

174
#### Matcher-Based Conditions
175

176
```java { .api }
177
/**
178
 * Wait until AtomicReference value matches condition
179
 * @param atomic the AtomicReference to monitor
180
 * @param matcher Hamcrest matcher for the reference value
181
 * @return final reference value when condition is met
182
 */
183
<V> V untilAtomic(AtomicReference<V> atomic, Matcher<? super V> matcher);
184
```
185

186
#### Consumer-Based Assertions
187

188
```java { .api }
189
/**
190
 * Wait until AtomicReference value passes consumer assertion
191
 * @param atomic the AtomicReference to monitor
192
 * @param matcher consumer that performs assertions on the value
193
 */
194
<V> void untilAtomic(AtomicReference<V> atomic, Consumer<? super V> matcher);
195
```
196

197
**AtomicReference Examples:**
198
```java
199
AtomicReference<String> status = new AtomicReference<>();
200
AtomicReference<List<String>> results = new AtomicReference<>();
201
AtomicReference<ConnectionState> connectionState = new AtomicReference<>();
202

203
// Wait for reference to be set
204
String finalStatus = await().untilAtomic(status, notNullValue());
205

206
// Wait for specific value
207
await().untilAtomic(status, equalTo("COMPLETED"));
208

209
// Wait for reference with complex object conditions
210
await().untilAtomic(results, hasSize(greaterThan(0)));
211

212
// Wait using consumer assertions
213
await().untilAtomic(connectionState, state -> {
214
    assertThat(state).isNotNull();
215
    assertThat(state.isConnected()).isTrue();
216
    assertThat(state.getLatency()).isLessThan(Duration.ofMillis(100));
217
});
218

219
// Wait for enum state change
220
await().untilAtomic(connectionState, 
221
    state -> state == ConnectionState.ESTABLISHED);
222

223
// Complex reference conditions
224
AtomicReference<Map<String, Object>> configuration = new AtomicReference<>();
225
await().untilAtomic(configuration, config -> {
226
    assertThat(config).isNotNull();
227
    assertThat(config).containsKey("database.url");
228
    assertThat(config).containsKey("api.key");
229
    assertThat(config.size()).isGreaterThan(5);
230
});
231
```
232

233
### Atomic Variables in Concurrent Scenarios
234

235
Patterns for testing concurrent operations with atomic variables.
236

237
#### Producer-Consumer Scenarios
238

239
```java
240
// Producer thread updates counter
241
AtomicInteger itemsProduced = new AtomicInteger(0);
242
AtomicInteger itemsConsumed = new AtomicInteger(0);
243

244
// Wait for producer to generate items
245
await().untilAtomic(itemsProduced, greaterThanOrEqualTo(100));
246

247
// Wait for consumer to process items
248
await().untilAtomic(itemsConsumed, greaterThanOrEqualTo(50));
249

250
// Wait for production/consumption balance
251
await().until(() -> {
252
    int produced = itemsProduced.get();
253
    int consumed = itemsConsumed.get();
254
    return produced > 0 && consumed >= produced / 2;
255
});
256
```
257

258
#### Multi-Stage Processing
259

260
```java
261
AtomicInteger stage1Complete = new AtomicInteger(0);
262
AtomicInteger stage2Complete = new AtomicInteger(0);
263
AtomicBoolean pipelineReady = new AtomicBoolean(false);
264

265
// Wait for pipeline stages
266
await().untilAtomic(stage1Complete, greaterThanOrEqualTo(100));
267
await().untilAtomic(stage2Complete, greaterThanOrEqualTo(50));
268
await().untilTrue(pipelineReady);
269

270
// Or wait for all stages combined
271
await().until(() -> 
272
    stage1Complete.get() >= 100 && 
273
    stage2Complete.get() >= 50 && 
274
    pipelineReady.get());
275
```
276

277
#### Resource Pool Monitoring
278

279
```java
280
AtomicInteger activeConnections = new AtomicInteger(0);
281
AtomicInteger availableConnections = new AtomicInteger(10);
282

283
// Wait for connections to be available
284
await().untilAtomic(availableConnections, greaterThan(0));
285

286
// Wait for load to decrease
287
await().untilAtomic(activeConnections, lessThan(5));
288

289
// Wait for pool to stabilize
290
await().until(() -> {
291
    int active = activeConnections.get();
292
    int available = availableConnections.get();
293
    return active + available == 10; // Total pool size
294
});
295
```