Table of Contents

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 -r of 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 Cache folder under AdminDirectory holds {CacheDbId}.db.lock beside 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-zip enters 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}.db open for writing, as right after a play, and 200 once the instance has been idle for some minutes (measured at nine). /copy of that folder answers 400 on Linux while the instance runs and leaves behind the Cache-Copy-NN folder 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. /download of the lock file answers 400 on Linux and 200 with no bytes on Windows. /delete of 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 flock answers a taken lock with an error other than EWOULDBLOCK, which .NET ignores — by its source, Linux's CIFS client answers EACCES; this was not run — and a process run with System.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 the Cache folder.

See Also

  • Program and Hosting — where AppBegin opens 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 Cache folder, described above
  • Configuration — the HiNC:CacheDbId key, and the environment name it overrides