The step-cache file
The host's step cache is Cache/{CacheDbId}.db beneath the admin directory.
CacheDbId is the HiNC:CacheDbId configuration value when one is set and
the hosting environment name otherwise. Program and Hosting is
where AppBegin is given that path.
From 3.2.57 on, a step-cache file has one storage at a time, in a process and across processes. A
SqliteStepStorage holds its file's lock file, {path}.lock — an empty file,
opened for writing and kept open from the storage's construction to its dispose — and a storage
that cannot take the lock of the path it was asked for leaves the file at that path alone and
keeps its steps, for its whole life, in a file of its own beside it:
{name}-pid{process id}{extension}, or -pid{process id}-2 to -9 for further storages of one
process, and an IOException naming the path when none of them can be taken. It logs one Warning
that names the path asked for and the file taken; a storage built without a logger says nothing.
DatabasePath is the file in use, so for this host that is
SqliteStepStorage.Default.DatabasePath: Cache/{CacheDbId}.db, or
Cache/{CacheDbId}-pid{process id}.db.
That is what keeps two processes under one environment name apart. An instance started a second
time builds its storage before it fails to bind the port the first one holds; earlier builds reset
the first one's file there, and a build with the lock file takes {CacheDbId}-pid{process id}.db,
says so in the Warning, fails to bind and ends, the first one's rows untouched. An instance that
does start beside the first — the same name on another address — plays into its own file for as
long as it lives.
No storage deletes a file when it is disposed. The file at the path asked for is reset by the next
start, as before: the constructor of LocalProjectService resets the default storage, while
building a storage keeps the rows it finds. Its lock file stays in the folder, empty, for good. A
process's own file is removed, with its -wal and -shm side files and its lock file, by the next
storage built on the path once nothing holds that file's lock — its process is gone, or its storage
was disposed; a file of that name that has no lock file beside it is left alone.
How the lock file is held differs by system, because the systems lock differently:
- Windows — held open for writing, shared for reading and nothing more. A second open for
writing, which is what another storage tries, is refused, and so are a delete and a rename of the
file. A copy of the file (Windows Explorer,
robocopy,xcopy,File.Copy) and a reader that itself shares writing get in and read the empty file. A reader that shares reading only (File.OpenRead,ZipFile.CreateEntryFromFile) is refused. - Linux — held with no sharing, the one share mode for which .NET takes an exclusive lock
there; for any other it takes a shared one, which would let a second storage in. The lock is
advisory: a program that asks for no lock reads the file regardless —
cp -rof the folder copied it — and a .NET reader is refused.
The web service's own file routes (File Explorer Page) meet the
lock file in an instance's Cache folder:
- The step cache's lock file. From 3.2.57 on, the
Cachefolder underAdminDirectoryholds{CacheDbId}.db.lockbeside the instance's step cache: an empty file the instance holds open while it runs (above), and the instance that answers a request is the one holding it./download-zipenters a file of length 0 that is not a link as an empty entry carrying the file's time, without opening it, so the archive of that folder holds the lock file as an empty entry; any other file is opened as before. On Windows the archive of that folder answers 400 while the instance has the database file{CacheDbId}.dbopen for writing, as right after a play, and 200 once the instance has been idle for some minutes (measured at nine)./copyof that folder answers 400 on Linux while the instance runs and leaves behind theCache-Copy-NNfolder it had begun: the copy goes file by file and stops at the first file it cannot open (in the runs measured the lock file came first and the folder was empty); on Windows it copied the folder, the lock file as an empty file, with the instance idle./downloadof the lock file answers 400 on Linux and 200 with no bytes on Windows./deleteof it is refused by Windows and not by Linux, where a second start of the same instance then resets the running one's step cache, as it did before 3.2.57: leave the file alone while the instance runs.
Not covered:
- A build before 3.2.57 neither takes the lock nor heeds it. Started beside a newer one on the same path it resets the file under it, and a newer one started beside it finds the lock free and resets the file under the older one.
- On Linux, a file system whose
flockanswers a taken lock with an error other thanEWOULDBLOCK, which .NET ignores — by its source, Linux's CIFS client answersEACCES; this was not run — and a process run withSystem.IO.DisableFileLocking. There every storage takes the path it was asked for. - On Linux, a lock file deleted while it is held: the next storage makes a new one and takes the path. The File Explorer page's Delete can do that; Windows refuses the delete.
- A reader that has the lock file open at the instant a storage is built sends that storage to a file of its own: on Linux a .NET reader, on Windows one that does not share writing, such as a copy tool reading the file at that instant.
Source Code Path
See HiNC App Anatomy for git repository links.
HiAPI Engine
HiNc/SqliteUtils/SqliteStepStorage.cs— the lock file a storage holds, and the file of its own a storage takes when it cannot take the lock.
Web Application
HiNC-2025-webservice:
Common/FileExplorerController.cs— the file routes that meet the lock file in theCachefolder.
See Also
- Program and Hosting — where
AppBeginopens this file, and the per-user default a missing path would fall back to - File Explorer Page — the file routes that meet this lock file
in an instance's
Cachefolder, described above - Configuration — the
HiNC:CacheDbIdkey, and the environment name it overrides