1use std::fmt;
16use std::future::ready;
17use std::ops::{Deref, DerefMut};
18use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
19
20use tokio::sync::OwnedMutexGuard;
21
22use crate::conditional::{
23 CommitError, CommitFuture, DeferredFailure, RollbackFuture, SetMode, SetScope, SetScopeId,
24 SetScopeRequest, current_set_scope,
25};
26
27pub struct ScopeGate {
36 lock: Arc<tokio::sync::Mutex<()>>,
38 owner: Mutex<Option<(SetScopeId, SetMode)>>,
40}
41
42impl ScopeGate {
43 pub fn new() -> Arc<Self> {
45 Arc::new(Self {
46 lock: Arc::new(tokio::sync::Mutex::new(())),
47 owner: Mutex::new(None),
48 })
49 }
50
51 fn owner(&self) -> Option<(SetScopeId, SetMode)> {
53 *self.owner.lock().unwrap_or_else(PoisonError::into_inner)
54 }
55
56 fn set_owner(&self, owner: Option<(SetScopeId, SetMode)>) {
57 *self.owner.lock().unwrap_or_else(PoisonError::into_inner) = owner;
58 }
59
60 fn owned_by_current(&self) -> Option<SetMode> {
62 let current = current_set_scope()?;
63 self.owner()
64 .and_then(|(id, mode)| (id == current).then_some(mode))
65 }
66}
67
68impl fmt::Debug for ScopeGate {
69 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70 f.debug_struct("ScopeGate")
71 .field("owner", &self.owner())
72 .finish_non_exhaustive()
73 }
74}
75
76pub struct ScopedGuard<'a, T>(MutexGuard<'a, T>);
82
83impl<T> Deref for ScopedGuard<'_, T> {
84 type Target = T;
85
86 fn deref(&self) -> &T {
87 &self.0
88 }
89}
90
91impl<T> DerefMut for ScopedGuard<'_, T> {
92 fn deref_mut(&mut self) -> &mut T {
93 &mut self.0
94 }
95}
96
97impl<T: fmt::Debug> fmt::Debug for ScopedGuard<'_, T> {
98 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
99 self.0.fmt(f)
100 }
101}
102
103type Validate<T> = Box<dyn FnOnce(&T, &T) -> Vec<DeferredFailure> + Send>;
107
108pub struct ScopedState<T> {
129 value: Arc<Mutex<T>>,
130 gate: Arc<ScopeGate>,
131}
132
133impl<T> Clone for ScopedState<T> {
134 fn clone(&self) -> Self {
135 Self {
136 value: Arc::clone(&self.value),
137 gate: Arc::clone(&self.gate),
138 }
139 }
140}
141
142impl<T: Default> Default for ScopedState<T> {
143 fn default() -> Self {
144 Self::new(T::default())
145 }
146}
147
148impl<T: fmt::Debug> fmt::Debug for ScopedState<T> {
149 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
150 f.debug_struct("ScopedState")
151 .field("value", &self.value)
152 .field("gate", &self.gate)
153 .finish()
154 }
155}
156
157impl<T> ScopedState<T> {
158 pub fn new(value: T) -> Self {
160 Self::with_gate(value, ScopeGate::new())
161 }
162
163 pub fn with_gate(value: T, gate: Arc<ScopeGate>) -> Self {
165 Self {
166 value: Arc::new(Mutex::new(value)),
167 gate,
168 }
169 }
170
171 pub fn gate(&self) -> &Arc<ScopeGate> {
174 &self.gate
175 }
176
177 pub async fn lock(&self) -> ScopedGuard<'_, T> {
184 if self.gate.owned_by_current().is_none() {
185 let _gate = self.gate.lock.lock().await;
191 return self.lock_unscoped();
192 }
193 self.lock_unscoped()
194 }
195
196 pub fn lock_unscoped(&self) -> ScopedGuard<'_, T> {
199 ScopedGuard(self.value.lock().unwrap_or_else(PoisonError::into_inner))
200 }
201
202 pub fn deferring(&self) -> bool {
210 self.gate.owned_by_current() == Some(SetMode::Atomic)
211 }
212}
213
214impl<T: Clone + Send + 'static> ScopedState<T> {
215 pub async fn open<V>(&self, request: SetScopeRequest<'_>, validate: V) -> Box<dyn SetScope>
235 where
236 V: FnOnce(&T, &T) -> Vec<DeferredFailure> + Send + 'static,
237 {
238 let held = self.gate.owner().is_some_and(|(id, _)| id == request.scope);
239 let permit = if held {
240 None
241 } else {
242 let permit = Arc::clone(&self.gate.lock).lock_owned().await;
243 self.gate.set_owner(Some((request.scope, request.mode)));
244 Some(permit)
245 };
246 let atomic = request.mode == SetMode::Atomic;
247 let snapshot = atomic.then(|| self.lock_unscoped().clone());
248 Box::new(StateScope {
249 value: Arc::clone(&self.value),
250 gate: Arc::clone(&self.gate),
251 permit,
252 snapshot,
253 validate: atomic.then(|| Box::new(validate) as Validate<T>),
254 })
255 }
256}
257
258struct StateScope<T> {
260 value: Arc<Mutex<T>>,
261 gate: Arc<ScopeGate>,
262 permit: Option<OwnedMutexGuard<()>>,
265 snapshot: Option<T>,
267 validate: Option<Validate<T>>,
268}
269
270impl<T> StateScope<T> {
271 fn restore(&mut self) {
273 if let Some(before) = self.snapshot.take() {
274 *self.value.lock().unwrap_or_else(PoisonError::into_inner) = before;
275 }
276 }
277}
278
279impl<T: Send + 'static> SetScope for StateScope<T> {
280 fn commit(mut self: Box<Self>) -> CommitFuture {
281 let failures = match (self.snapshot.as_ref(), self.validate.take()) {
282 (Some(before), Some(validate)) => {
283 let after = self.value.lock().unwrap_or_else(PoisonError::into_inner);
284 validate(before, &after)
285 }
286 _ => Vec::new(),
287 };
288 let result = if failures.is_empty() {
289 self.snapshot = None;
290 Ok(())
291 } else {
292 self.restore();
293 Err(CommitError::Rejected(failures))
294 };
295 drop(self);
296 Box::pin(ready(result))
297 }
298
299 fn rollback(self: Box<Self>) -> RollbackFuture {
300 drop(self);
302 Box::pin(ready(()))
303 }
304}
305
306impl<T> Drop for StateScope<T> {
307 fn drop(&mut self) {
308 self.restore();
311 if let Some(permit) = self.permit.take() {
312 self.gate.set_owner(None);
313 drop(permit);
314 }
315 }
316}
317
318#[cfg(test)]
319mod tests {
320 use std::collections::BTreeMap;
321 use std::future::Future;
322 use std::pin::pin;
323 use std::task::{Context, Poll, Waker};
324
325 use jmap_types::{Id, SetError};
326 use serde_json::Value;
327
328 use super::*;
329 use crate::SetErrorType;
330 use crate::conditional::{SetOp, in_set_scope};
331
332 #[derive(Debug, Clone, Default, PartialEq)]
335 struct Store {
336 names: BTreeMap<String, String>,
337 state: u64,
338 log: Vec<String>,
339 }
340
341 impl Store {
342 fn write(&mut self, id: &str, name: &str) {
343 self.names.insert(id.to_owned(), name.to_owned());
344 self.state += 1;
345 self.log.push(id.to_owned());
346 }
347 }
348
349 fn seeded() -> ScopedState<Store> {
350 let state = ScopedState::<Store>::default();
351 state.lock_unscoped().write("a", "one");
352 state
353 }
354
355 fn now<F: Future>(fut: F) -> F::Output {
358 let mut cx = Context::from_waker(Waker::noop());
359 match pin!(fut).poll(&mut cx) {
360 Poll::Ready(out) => out,
361 Poll::Pending => panic!("waited, but nothing should block"),
362 }
363 }
364
365 fn waits<F: Future>(fut: F) -> bool {
367 let mut cx = Context::from_waker(Waker::noop());
368 pin!(fut).poll(&mut cx).is_pending()
369 }
370
371 fn request(mode: SetMode) -> SetScopeRequest<'static> {
372 SetScopeRequest::new("Probe/set", "Probe", None, mode, &Value::Null)
373 }
374
375 fn no_checks(_: &Store, _: &Store) -> Vec<DeferredFailure> {
376 Vec::new()
377 }
378
379 #[test]
380 fn lock_never_waits_with_no_scope_open() {
381 let state = seeded();
382 assert_eq!(now(state.lock()).names["a"], "one");
383 let scope = now(state.open(request(SetMode::Atomic), no_checks));
385 now(scope.commit()).unwrap();
386 now(state.lock()).write("b", "two");
387 assert_eq!(state.lock_unscoped().names.len(), 2);
388 }
389
390 #[tokio::test]
391 async fn unscoped_read_and_write_wait_for_another_tasks_scope() {
392 let state = seeded();
393 let req = request(SetMode::Atomic);
394 let scope = state.open(req, no_checks).await;
395 in_set_scope(req.scope, async { state.lock().await.write("a", "scoped") }).await;
396
397 let reader = state.clone();
398 let read = tokio::spawn(async move { reader.lock().await.names["a"].clone() });
399 let writer = state.clone();
400 let write = tokio::spawn(async move { writer.lock().await.write("b", "outside") });
401 for _ in 0..10 {
402 tokio::task::yield_now().await;
403 }
404 assert!(!read.is_finished(), "a read must not see the open scope");
405 assert!(!write.is_finished(), "a write must wait for the open scope");
406
407 scope.rollback().await;
408 assert_eq!(read.await.unwrap(), "one");
410 write.await.unwrap();
411 let after = state.lock_unscoped();
412 assert_eq!(after.names["a"], "one");
413 assert_eq!(after.names["b"], "outside");
414 assert_eq!(after.log, ["a", "b"]);
415 }
416
417 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
421 async fn unscoped_writes_racing_rolled_back_scopes_are_kept() {
422 const WRITES: u64 = 2000;
423 let state = ScopedState::new(0_u64);
424 let writers: Vec<_> = (0..2)
425 .map(|_| {
426 let state = state.clone();
427 tokio::spawn(async move {
428 for _ in 0..WRITES {
429 *state.lock().await += 1;
430 tokio::task::yield_now().await;
431 }
432 })
433 })
434 .collect();
435 let scoper = {
436 let state = state.clone();
437 tokio::spawn(async move {
438 for _ in 0..WRITES {
439 let req = request(SetMode::Atomic);
440 let scope = state.open(req, |_: &u64, _: &u64| Vec::new()).await;
441 in_set_scope(req.scope, async { *state.lock().await += 1_000_000 }).await;
442 scope.rollback().await;
443 }
444 })
445 };
446 for w in writers {
447 w.await.unwrap();
448 }
449 scoper.await.unwrap();
450 assert_eq!(*state.lock_unscoped(), 2 * WRITES);
451 }
452
453 #[test]
454 fn scope_owner_reenters_without_waiting() {
455 let state = seeded();
456 let req = request(SetMode::Isolated);
457 let _scope = now(state.open(req, no_checks));
458 let len = now(in_set_scope(req.scope, async {
459 state.lock().await.write("b", "two");
460 state.lock().await.write("c", "three");
461 state.lock().await.names.len()
462 }));
463 assert_eq!(len, 3);
464 assert!(waits(state.lock()));
466 }
467
468 #[test]
469 fn states_sharing_a_gate_do_not_deadlock() {
470 let a = seeded();
471 let b = ScopedState::with_gate(Store::default(), Arc::clone(a.gate()));
472 let req = request(SetMode::Atomic);
473 let scope_a = now(a.open(req, no_checks));
474 let scope_b = now(b.open(req, no_checks));
477 now(in_set_scope(req.scope, async {
478 a.lock().await.write("a", "changed");
479 b.lock().await.write("x", "new");
480 a.lock().await.write("a", "again");
481 }));
482 assert!(waits(b.lock()), "b is gated by a's scope");
483
484 now(scope_b.rollback());
486 assert_eq!(*b.lock_unscoped(), Store::default());
487 assert!(waits(a.lock()));
488 now(scope_a.commit()).unwrap();
489 assert_eq!(now(a.lock()).names["a"], "again");
490 assert_eq!(*now(b.lock()), Store::default());
491 }
492
493 #[test]
494 fn rollback_restores_state_and_change_log() {
495 let state = seeded();
496 let before = state.lock_unscoped().clone();
497 let req = request(SetMode::Atomic);
498 let scope = now(state.open(req, no_checks));
499 now(in_set_scope(req.scope, async {
500 let mut s = state.lock().await;
501 s.write("a", "renamed");
502 s.write("b", "created");
503 }));
504 assert_eq!(state.lock_unscoped().state, 3);
505 now(scope.rollback());
506 assert_eq!(*state.lock_unscoped(), before);
507 assert_eq!(before.state, 1);
508 assert_eq!(before.log, ["a"]);
509 }
510
511 #[test]
512 fn dropping_a_scope_rolls_back_and_frees_the_gate() {
513 let state = seeded();
514 let before = state.lock_unscoped().clone();
515 let req = request(SetMode::Atomic);
516 let scope = now(state.open(req, no_checks));
517 now(in_set_scope(req.scope, async {
518 state.lock().await.write("b", "two")
519 }));
520 drop(scope);
521 assert_eq!(*now(state.lock()), before);
522 }
523
524 #[test]
525 fn commit_keeps_changes_validated_against_the_final_state() {
526 let state = seeded();
527 let req = request(SetMode::Atomic);
528 let scope = now(state.open(req, |before: &Store, after: &Store| {
529 assert_eq!(before.names["a"], "one");
530 assert_eq!(after.names["a"], "two");
531 Vec::new()
532 }));
533 now(in_set_scope(req.scope, async {
534 state.lock().await.write("a", "two")
535 }));
536 now(scope.commit()).unwrap();
537 let after = state.lock_unscoped();
538 assert_eq!((after.names["a"].as_str(), after.state), ("two", 2));
539 }
540
541 #[test]
542 fn rejected_commit_restores_and_reports_the_failures() {
543 let state = seeded();
544 let before = state.lock_unscoped().clone();
545 let req = request(SetMode::Atomic);
546 let scope = now(state.open(req, |_: &Store, after: &Store| {
548 let mut seen = BTreeMap::new();
549 after
550 .names
551 .iter()
552 .filter(|(_, name)| seen.insert(name.as_str(), ()).is_some())
553 .map(|(id, _)| {
554 DeferredFailure::new(
555 SetOp::Update(Id::new_validated(id).unwrap()),
556 SetError::new(SetErrorType::AlreadyExists),
557 )
558 })
559 .collect()
560 }));
561 now(in_set_scope(req.scope, async {
562 state.lock().await.write("b", "one")
563 }));
564 let Err(CommitError::Rejected(failures)) = now(scope.commit()) else {
565 panic!("a duplicate name must reject the commit");
566 };
567 assert_eq!(failures.len(), 1);
568 assert_eq!(
569 failures[0].op,
570 SetOp::Update(Id::new_validated("b").unwrap())
571 );
572 assert_eq!(
573 *now(state.lock()),
574 before,
575 "rejected: rolled back, gate free"
576 );
577 }
578
579 #[test]
580 fn isolated_scope_keeps_its_writes_and_skips_validate() {
581 let state = seeded();
582 let req = request(SetMode::Isolated);
583 let scope = now(
584 state.open(req, |_: &Store, _: &Store| -> Vec<DeferredFailure> {
585 panic!("an isolated scope has no final-state check")
586 }),
587 );
588 now(in_set_scope(req.scope, async {
589 assert!(!state.deferring());
590 state.lock().await.write("b", "two");
591 }));
592 now(scope.commit()).unwrap();
593 assert_eq!(now(state.lock()).names.len(), 2);
594
595 let req = request(SetMode::Isolated);
598 let scope = now(state.open(req, no_checks));
599 now(in_set_scope(req.scope, async {
600 state.lock().await.write("c", "three")
601 }));
602 now(scope.rollback());
603 assert_eq!(now(state.lock()).names.len(), 3);
604 }
605
606 #[test]
607 fn deferring_only_inside_the_running_atomic_scope() {
608 let state = seeded();
609 assert!(!state.deferring());
610 let req = request(SetMode::Atomic);
611 let scope = now(state.open(req, no_checks));
612 assert!(!state.deferring(), "not in the scope");
613 assert!(now(in_set_scope(req.scope, async { state.deferring() })));
614 let other = SetScopeId::next();
615 assert!(!now(in_set_scope(other, async { state.deferring() })));
616 drop(scope);
617 assert!(!now(in_set_scope(req.scope, async { state.deferring() })));
618 }
619}