The home folder and how settings are saved

DataMind Oda keeps the settings files it writes, the caches it builds and the paths it watches in one home folder on this computer. This page is the reference for that folder: how it is resolved, how it is shown, and what keeps a settings save safe. The folder as it appears in everyday use is on Oda's home folder and settings files; what the settings file itself contains is on The profile settings file.

How the home folder is resolved

Oda uses the first of these that is actually set:

1. A folder path set for the run.
2. The home folder named in the environment Oda starts in.
3. The default: a folder inside your user folder.

• A blank value counts as not set. A value that is empty, or only spaces, is ignored, and Oda falls through to the next choice. An empty value never resolves the home to the folder Oda was started from.
• A leading ~ stands for your user folder. A configured path may begin with ~ or ~/, and Oda expands it to your user folder; a name after the tilde, such as ~name, is taken as written.

How the home folder is shown

• A short form, never the full path. Oda writes the home folder in a short form such as ~/<folder>, where ~ stands for your user folder; a home you set yourself is shown by the name of the setting you used. The full path on your computer is never written into what Oda shows you, so a message you copy or share does not reveal your machine's layout.
• The ~ abbreviation is for POSIX-style paths. Where Oda shortens a displayed path with ~, a Windows-style path is not abbreviated this way; it is shown as it is.
• Links are built from text. When Oda builds a path into a link or a preview, it works by text alone: it does not look the path up on the computer, and a . or .. part stays as written.

Where caches live

Caches live under the resolved home, inside its cache folder. Oda derives cache paths from the same resolved home as the settings files, and working out a path creates nothing on the computer; the cache folder holds the caches Oda builds as it works.

What keeps a settings save safe

When Oda saves a settings file, it does not rewrite the file in place. Every save works in three steps:

1. It takes the lock. Oda creates a lock file beside the target: the file's name plus .lock. The lock records the process that is writing, so a second save waits instead of writing at the same time; reading is never blocked, because only writers contend. If another save holds the lock, Oda waits with pauses that start small and grow, up to about two seconds by default, and then stops waiting instead of writing. A save that has a slower step to wait for, such as a network round trip, can be given more time.
2. It writes beside the target. Oda writes the new content to a temporary file next to the settings file, then renames it over the target. Anyone reading at that moment sees the old file or the new one, never something written halfway.
3. It cleans up. Oda removes the lock when the save ends, and removes the temporary file if the save could not finish. A failed save leaves the settings file as it was, and a waiting save never removes a lock it did not create.

More behaviours you may meet:

• Windows retries. On Windows, a brief sharing error, such as another program holding the file open for a moment, is retried before the save gives up; if the file still cannot be replaced, the save does not happen and the target keeps its old content.
• Links and permissions. If the path is a symbolic link, Oda replaces the link itself and leaves the file it points to alone. A replacement is created with the permissions Oda sets for settings files, so a file that had wider permissions is narrowed to them.
• No flush for a sudden power loss. The replacement is not flushed for a power loss, so the very newest save can be lost that way; the file still holds the old content or the new one, never something half-written.

Changes you save in settings forms are written this way; Live plugin settings covers those forms.

When a save cannot get the lock

If the wait runs out, the save does not happen, and Oda reports that it timed out waiting for the writer lock, naming the lock file's path. Try the change again. If the saves keep timing out, an earlier save has usually crashed and left its lock behind: that lock makes later saves wait and time out until it is removed, and it is removed only after checking that no writer still owns it.

Watching a path before it exists

Oda also watches paths for changes. A path does not have to exist yet: Oda resolves the deepest folder in the path that already exists and keeps the rest, so the path is under watch from the moment it is created. If the nearest part of the path that exists is a file rather than a folder, the path is refused. What a watch does with a change is on Hot reload.

Questions, answered

Where does Oda keep its home folder?

By default, in a folder inside your user folder. A run can set a folder path, or name a home in the environment Oda starts in; the first of these that is set wins. The settings files Oda writes, the caches it builds and the paths it watches live under it, and Oda shows the location in a short form, never the full path.

Can I move Oda's home folder?

Yes. Name the folder you want in the home setting of the environment you start Oda in, and Oda uses it the next time it starts. A blank or spaces-only value is ignored, so an empty setting moves nothing.

Why does Oda shorten folder paths when it shows them?

Oda writes the home folder in a short form such as ~/<folder>, where ~ stands for your user folder, and a home you set yourself is shown by the name of the setting you used. The full path on your computer is never written into what Oda shows you, so a message you copy or share does not reveal your machine's layout.

Does the ~ shorthand work for Windows-style paths?

Not for displayed paths in general: the ~ abbreviation covers POSIX-style paths, and a Windows-style path is shown as it is. The home folder itself keeps its short form.

What happens if the home setting is left empty?

An empty value, or one with only spaces, counts as not set: Oda ignores it and falls through to the next choice. An empty value never resolves the home to the folder Oda was started from.

Where do Oda's caches live?

Under the resolved home, inside its cache folder. Oda derives cache paths from the same resolved home as the settings files, and working out a path creates nothing on the computer; the cache folder holds the caches Oda builds as it works.

What happens if two settings saves run at the same time?

One takes the lock and writes; the other waits with pauses that start small and grow, up to about two seconds by default, and only then stops instead of writing. The two saves never write at the same time, and a waiting save never removes a lock it did not create. Reading is never blocked.

Why did my save report a timed-out writer lock?

Another save was in progress, or a save that crashed left the lock behind. Try the change again; if it keeps failing, ask DataMind support to clear the lock. Do not remove the lock file yourself: a lock is cleared only after checking that no writer still owns it.

What happens to a symbolic link when a settings file is saved?

Oda replaces the link itself and leaves the file it points to alone. The replacement is created with the permissions Oda sets for settings files, so a file that had wider permissions is narrowed to them on the next save.

Could a power cut lose my newest settings change?

Yes, in one narrow case: the replacement is not flushed for a sudden power loss, so the very newest save can be lost that way. Even then the file holds the old content or the new one, never something half-written.

Can a path be watched before it exists?

Yes. Oda resolves the deepest folder in the path that already exists and keeps the rest, so the path is under watch from the moment it is created. What a watch does with a change is on Hot reload.