save method

Future<String?> save({
  1. String? message,
})

Commits the current values, refusing the write if the file moved.

Writes are serialized — one queue in front of the file. The file has several writers in one process, and each save is a compare-and-swap on the head the previous one left: two in flight at once would both carry the same expected head, and the second would be refused although nothing outside this process touched the file. Queued, each write commits the values as they are when its turn comes, over the head the write before it produced — so a later write also carries every key an earlier one set.

A refused write does not stall the queue: its exception reaches its own caller and the next write still runs.

With nothing in flight the write starts at once rather than behind an already-completed future: a future carries the zone it was made in, and a write queued behind one made elsewhere waits for that zone to run it.

Implementation

Future<String?> save({String? message}) {
  final previous = _writes;
  final result = previous == null
      ? _saveNow(message)
      : previous.then((_) => _saveNow(message));
  late final Future<void> tail;
  tail = result.then<void>((_) {}, onError: (Object _) {}).whenComplete(() {
    if (identical(_writes, tail)) _writes = null;
  });
  _writes = tail;
  return result;
}