TomLocalFileSystemStorage class
Containers on the local filesystem: a file, or a directory of files.
A multi-file changeset is applied all-or-nothing in three steps:
- Stage. Every write lands in a
.tom-tmpsibling of its target. A failure here removes the temps and leaves the container untouched. - Record. One intent file, intentName, names every rename and every delete the changeset makes. It is written to a temp and renamed into place, so it is either whole or absent — that rename is the commit point.
- Apply. The temps are renamed over their targets, the deletes are applied, and the intent is removed.
A crash before step 2 leaves temps beside an unchanged container; they are ignored by every read and swept by the next commit. A crash after it leaves an intent, and every entry point — reads included — finishes the recorded renames and deletes before it looks at the container. So no reader ever sees a half-applied changeset: it sees the old container until the intent exists and the whole new one from then on.
The head token is a digest of the container's own state — for a single file its size and modification time, for a directory the same over every part. It is opaque and only ever compared, which is what makes it interchangeable with a git commit sha. A file's time is read to the millisecond, so a commit writes only once the clock is past the previous time of every file it replaces: two same-size writes inside one millisecond would otherwise leave the head where it was, and a device holding the older head could commit over the newer write.
- Inheritance
-
- Object
- TomStorage
- TomLocalFileSystemStorage
Constructors
- TomLocalFileSystemStorage({TomLocalCommitProbe? probe})
-
const
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- maxObjectBytes → int?
-
The largest a single path in a TomChangeset may be, or null when
the backend imposes no limit of its own.
no setterinherited
- probe → TomLocalCommitProbe?
-
Called between the steps of a directory commit — a test's way of failing
one midway, as a crash would. Null in every production composition.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
adoptBackoff(
TomBackoffPolicy policy) → void -
Adopts how long to hold off after a rate limit that stated no instant.
inherited
-
cacheMetaScope(
String location) → List< String> ? -
The
meta/key prefix this backend keeps the records for the storage locationlocationunder, or null when it keeps none.inherited -
close(
) → void -
inherited
-
commit(
String locator, TomChangeset changeset, {String? expectedHead, String? message, TomCommitProgressSink? onProgress}) → Future< String> -
Applies
changesetatomically, refusing the write if the container has moved away fromexpectedHead.override -
delete(
String locator) → Future< void> -
Removes the whole container.
override
-
handles(
String locator) → bool -
Anything without a
<scheme>:prefix. A bare Windows drive letter (C:\…) is a path, not a scheme, so it is deliberately not matched.override -
headOf(
String locator) → Future< String?> -
The current revision of the container, or null when it does not exist.
override
-
headsOf(
Iterable< String> locators) → Future<Map< String, String?> > -
headOf for several containers at once.
inherited
-
list(
String locator) → Future< List< TomStorageEntry> > -
Entries directly inside the container at
locator.override -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
readBundle(
String locator) → Future< TomBundleMedium> -
A read-through view of the folder, not a copy of it.
override
-
readBytes(
String locator) → Future< Uint8List> -
The bytes of the single-file artifact at
locator.override -
toString(
) → String -
A string representation of this object.
inherited
-
withinPass<
T> (Future< T> body()) → Future<T> -
Runs
bodyas one pass: a stretch of work whose reads may share what the pass has already established about the remote.inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Constants
- intentName → const String
- The recorded intent of a directory commit, inside the container.
- lfsRemedy → const String
-
The remedy here is a different one from the GitHub backend's, and that is
the whole reason the sentence is supplied per backend rather than baked
into the refusal: on disk a pointer means the working tree was never
smudged, which
git lfs pullfixes. The diagnosis is identical; what the reader can do about it is not. - tempSuffix → const String
-
Marks a staged write. Shared with
TomDirectoryBundleMedium, so a temp either of them leaves is invisible to the other.