Skip to content
Project referenceDevelopmentEngine ccf7d03f
Outdated
  • Explicit filesystem boundaries, atomic publication, shared leases, byte documents and process-owned output.

Core IO supplies reusable filesystem and lifetime mechanisms without depending on a build product, backend or game-domain catalog. Hosts choose physical paths; domain services consume narrow document or content contracts. Start with persisting a host document or managing process output.

Ownership, publication and observation are separate. PathBoundary checks a normalized path against an explicitly selected root. FileLease coordinates cooperating processes. AtomicFile and AtomicDirectory publish complete candidates. None of them independently grants permission to replace an arbitrary directory or defeats a noncooperating process changing a parent path.

Construct child paths from the root’s original normalized spelling. Containment uses ordinal spelling on every volume. RequireUnlinkedPath rejects observed links and reparse points; EnumerateFiles does not follow them. Repeat validation at the required phase boundary while holding the appropriate owner protection. PhysicalPathResolver caches observed link relationships only within one explicitly scoped observation phase.

Lease acquisition supports cancellation and a caller-selected timeout. Shared leases pin initialized generations against exclusive retirement. Keep persistent lock files after release; deleting them can split participants across different filesystem objects. CoordinatedFileLease acquires owner reading protection before waiting for its leaf and releases the leaf first.

IByteDocumentStore represents a small complete document. Null means absent; an empty array means present but empty. Writable file documents publish complete bytes atomically. Read-only documents own a copy and reject writes. Serialization and validation remain with the domain service that interprets the bytes.

OwnedReadStream owns its input stream and a separate lifetime pin. Disposal closes input before releasing the pin and retains unfinished responsibility after failure. Its read operations inherit the underlying stream’s behavior; the wrapper does not promise general concurrent I/O or marshal callbacks.

File publication requires a complete same-directory candidate. Create-only mode must reject collisions atomically, including empty existing targets; its Unix primitive requires hard-link support. No fallback exposes partly copied destination bytes. Candidate-name recognition exists for source discovery and confers no deletion authority.

Directory replacement needs caller-held reader/writer coordination. A failed cleanup after a committed install differs from an installation failure. Preserve DirectoryCleanupException’s new/backup paths and both failures when restoration also fails. Do not claim that a failed backup deletion means the new tree was never installed.

Process-owned directories publish explicit PID/start-time claims before payload use and register child participation before consumption. Unknown identity protects the directory. Failure to retire leaves a claim for later maintenance; it is not resolved by deleting the lock. Build caches layer their own artifact registration and dependency protection over these mechanisms.

These APIs are host CLR contracts, not game-script exports. Operating-system process claims require actual process-lifetime support. Atomic create-only file publication requires a compatible host primitive and filesystem; unsupported capabilities fail explicitly. Selecting a host filesystem primitive does not select an engine platform, target or backend.

The owning project’s tests cover publication, lease coordination, path spelling, process identity, byte-document reads and independent stream pins. Successful unit tests on one host do not certify every volume’s case/link semantics.

Browse atomic publishers, leases, documents, streams and process claims.

Project: Inno.Core.IO
Source: src/foundation/core/Inno.Core.IO/Inno.Core.IO.csproj

Type API Description
AtomicDirectory engine Provides rollback-safe installation of complete directory trees.
AtomicFile engine Provides durable same-directory file replacement without exposing partial destination content.
CoordinatedFileLease engine Holds a persistent owner gate throughout waiting for and using a retireable leaf lease.
DirectoryCleanupException engine Reports backup cleanup failure after a complete directory installation has already committed. The installed tree remains authoritative and must not be treated as a failed installation.
FileByteDocumentStore engine Stores one file document with atomic replacement using the common filesystem boundary.
FileLease engine Owns shared reading or exclusive writing rights coordinated by independent processes.
IByteDocumentStore engine Reads and replaces one complete document without prescribing its physical location.
OwnedReadStream engine Keeps an independent read stream and its lifetime pin owned together until both retire.
PathBoundary engine Resolves paths while enforcing an explicit filesystem ownership boundary.
PhysicalPathResolver engine Resolves filesystem aliases within one caller-owned reading phase without granting write authority.
ProcessOwnedDirectory engine Claims a new temporary directory before payload writes and preserves failed cleanup for later retirement.
ProcessOwnedDirectoryDescriptor engine Describes a recorded temporary directory without acquiring its producer’s rights.
ProcessOwnerStamp engine Identifies one process lifetime without retaining a process handle or confusing recycled identifiers.
ProcessOwnerState engine Describes whether an exact operating-system process lifetime can still own files.
ReadOnlyByteDocumentStore engine Owns an immutable document snapshot that cannot be replaced through its read boundary.