commit method
Future<String>
commit(
- String locator,
- TomChangeset changeset, {
- String? expectedHead,
- String? message,
- TomCommitProgressSink? onProgress,
override
Applies changeset atomically, refusing the write if the container has
moved away from expectedHead.
Pass a null expectedHead to create a container that does not exist yet;
a backend MUST fail with TomCasConflictException if one does.
Returns the new head.
onProgress, when given, receives TomCommitProgress as the
changeset's objects go up — before each and after the last. It is
optional on both sides: a caller need not ask, and a backend whose
save is effectively instantaneous need not report. Silence from a backend
is therefore not a failure to implement it; it is the honest answer for a
local filesystem write.
Implementation
@override
Future<String> commit(
String locator,
TomChangeset changeset, {
String? expectedHead,
String? message,
// Deliberately unused: a local save is a handful of `writeAsBytesSync`
// calls and is over before a frame renders, so reporting progress through
// it would be inventing a wait to display. The port makes the sink
// optional for exactly this backend.
TomCommitProgressSink? onProgress,
}) async {
tomGuardChangeset(locator, changeset, this);
final directory = !changeset.isSingleFile;
if (directory && Directory(locator).existsSync()) {
final dir = Directory(locator);
_recover(dir);
_sweep(dir);
} else if (!directory) {
final stray = File('$locator$tempSuffix');
if (stray.existsSync()) stray.deleteSync();
}
final actualHead = await headOf(locator);
if (actualHead != expectedHead) {
throw TomCasConflictException(
locator,
expectedHead: expectedHead,
actualHead: actualHead,
);
}
if (changeset.isEmpty) return actualHead ?? TomStorage.emptyHead;
if (!directory) {
final before = _modifiedTimes([locator]);
await _clockPast(before);
// One file is one rename, which the filesystem already makes atomic.
final temp = _stage({locator: changeset.containerBytes});
File(temp.keys.single).renameSync(locator);
_advancePast(before);
return (await headOf(locator))!;
}
final dir = Directory(locator)..createSync(recursive: true);
final before = _modifiedTimes([
for (final relative in changeset.writes.keys) p.join(dir.path, relative),
]);
await _clockPast(before);
final staged = _stage({
for (final entry in changeset.writes.entries)
p.join(dir.path, entry.key): entry.value,
});
try {
probe?.call(TomLocalCommitStep.staged);
_recordIntent(dir, staged, changeset.deletes);
} catch (_) {
// Before the commit point: the container is untouched, and the temps
// are all that has to go.
_discard(staged.keys);
rethrow;
}
// Past the commit point a failure is not undone. The intent stays, and
// the next access to the container finishes what it records.
probe?.call(TomLocalCommitStep.recorded);
_applyIntent(dir);
_advancePast(before);
return (await headOf(locator))!;
}