![]() |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
Namespaces | |
| namespace | detail |
Classes | |
| class | AtomicOutputFile |
| Own a staging stream and publish it by a checked single-file rename. More... | |
| class | CheckpointDirectory |
| struct | CheckpointFile |
| class | CheckpointOutputPublication |
| struct | OwnedCheckpointFile |
| struct | RelativeResult |
Outcome of computing target relative to anchor_dir. More... | |
Enumerations | |
| enum class | PathClass : int { Relative = 0 , AbsoluteSameVolume = 1 , AbsoluteCrossVolume = 2 , Invalid = 3 } |
| Classification of a makeRelative() result. More... | |
Functions | |
| std::filesystem::path | utf8_path (const std::string &utf8) |
| Convert borrowed path bytes into an owned native filesystem path. | |
| template<class P> requires std::same_as<std::remove_cvref_t<P>, std::filesystem::path> | |
| std::filesystem::path | utf8_path (P &&)=delete |
Passing an fs::path to utf8_path() is always a mistake — refuse it at compile time, on EVERY platform. | |
| std::string | path_utf8 (const std::filesystem::path &p, bool generic=false) |
| Copy a native path into the engine byte-string representation. | |
| template<class S> requires (!std::same_as<std::remove_cvref_t<S>, std::filesystem::path>) | |
| std::string | path_utf8 (S &&, bool=false)=delete |
The mirror guard: path_utf8() takes a path, never a string. | |
| std::FILE * | fopen_path (const std::filesystem::path &p, const char *mode) |
| Open a borrowed native path using platform C stdio. | |
| std::FILE * | fopen_utf8 (const std::string &utf8, const char *mode) |
| Convert engine path bytes and open a C stdio stream. | |
| bool | isAbsolutePath (const std::string &path) noexcept |
| Recognize platform-neutral absolute-looking path syntax. | |
| std::string | normaliseSeparators (const std::string &path) |
| Normalize separator and dot spelling without resolving parent segments. | |
| std::string | parentDir (const std::string &file_path) |
| Extract a directory token using normalized separator text. | |
| std::string | resolveRelative (const std::string &stored_token, const std::string &anchor_dir) |
| Join a stored token to a directory anchor using lexical normalization. | |
| RelativeResult | makeRelative (const std::string &target_absolute, const std::string &anchor_dir, int max_up_levels=16) |
| Compute a lexical relative token or return a classified absolute fallback. | |
| bool | checkpointNoReplaceAvailable () noexcept |
| Report compile-time support for exclusive checkpoint publication. | |
| void | publishCheckpointNoReplace (const std::filesystem::path &staging, const std::filesystem::path &destination) |
| Atomically publish a private file/directory without replacing any destination. | |
| uint64_t | checkpointFileSize (const std::filesystem::path &path) |
| Read a checkpoint companion's validated size. | |
| void | checkpointSeek (FILE *f, uint64_t offset) |
| Position an existing stream at an absolute checkpoint byte offset. | |
| std::shared_ptr< OwnedCheckpointFile > | copyCheckpointFile (const std::filesystem::path &source, uint64_t bytes, const std::filesystem::path &staging_base, int source_descriptor=-1) |
| Copy and verify an exact source prefix into a private companion file. | |
| hid_t | checkpointHdf5Access () |
| Create access properties using the locked native-descriptor checkpoint VFD. | |
| hid_t | createCheckpointHdf5 (const char *path, unsigned flags) |
| Create a checkpoint-compatible HDF5 result file. | |
| hid_t | openCheckpointHdf5 (const char *path, unsigned flags) |
| Open a checkpoint-compatible HDF5 result file. | |
| int | checkpointHdf5Descriptor (hid_t file) |
| Borrow the native descriptor of a sec2 or checkpoint-VFD file. | |
| FILE * | checkpointOpenOutput (const std::filesystem::path &path, bool existing=false) |
| Open a writable binary output for checkpoint restoration. | |
| int | checkpointFileDescriptor (FILE *stream) noexcept |
| Obtain a borrowed platform descriptor for a C stream. | |
| void | checkpointReadOutput (int descriptor, uint64_t offset, char *data, std::size_t bytes) |
| Read an exact output range through a borrowed seekable writer descriptor. | |
| std::recursive_mutex & | resultHdf5Mutex () |
| Access the shared recursive lock for result-file HDF5 operations. | |
| hid_t | createHdf5Dataset (hid_t location, const char *name, hid_t type, hid_t space, hid_t links, hid_t creation, hid_t access) |
| Create a dataset without wall-clock object timestamps. | |
| hid_t | createHdf5Group (hid_t location, const char *name, hid_t links, hid_t creation, hid_t access) |
| Create a group without wall-clock object timestamps. | |
| hid_t | createHdf5File (const char *path, unsigned flags, hid_t creation, hid_t access) |
| Create an HDF5 file without wall-clock object timestamps. | |
|
strong |
Classification of a makeRelative() result.
Callers use this to decide whether the produced string is usable as a portable token in a .inp file. Only Relative is portable; the absolute variants are returned when the relative form would be invalid or worse than the absolute one.
|
noexcept |
Obtain a borrowed platform descriptor for a C stream.
| [in] | stream | Borrowed open C stream, or null. |
| uint64_t openswmm::io::checkpointFileSize | ( | const std::filesystem::path & | path | ) |
Read a checkpoint companion's validated size.
| [in] | path | Borrowed non-symlink regular file to inspect. |
| std::runtime_error | File type or size is invalid. |
| std::filesystem::filesystem_error | Metadata inspection fails. |
| hid_t openswmm::io::checkpointHdf5Access | ( | ) |
Create access properties using the locked native-descriptor checkpoint VFD.
Serializes registration/property creation through resultHdf5Mutex. The VFD uses native descriptors with shared/exclusive nonblocking file locks; Windows opens with FILE_SHARE_DELETE so checkpoint publication can rename an open result file. Callers serialize subsequent HDF5 operations using the same mutex; file objects retain their own properties after this list closes.
| int openswmm::io::checkpointHdf5Descriptor | ( | hid_t | file | ) |
Borrow the native descriptor of a sec2 or checkpoint-VFD file.
Serializes metadata lookup with resultHdf5Mutex. Does not duplicate the descriptor: do not close it independently, and do not use it after the HDF5 file closes. The lock is released before return; caller must coordinate later descriptor IO with HDF5 file operations. May register the checkpoint driver while comparing VFD kinds.
| [in] | file | Borrowed live HDF5 file identifier; caller keeps it open throughout descriptor use. |
|
noexcept |
Report compile-time support for exclusive checkpoint publication.
| FILE * openswmm::io::checkpointOpenOutput | ( | const std::filesystem::path & | path, |
| bool | existing = false ) |
Open a writable binary output for checkpoint restoration.
| [in] | path | Borrowed output path in platform filesystem encoding. |
| [in] | existing | True opens an existing file without truncation; false exclusively creates a new file and fails if the path exists. |
| void openswmm::io::checkpointReadOutput | ( | int | descriptor, |
| uint64_t | offset, | ||
| char * | data, | ||
| std::size_t | bytes ) |
Read an exact output range through a borrowed seekable writer descriptor.
| [in] | descriptor | Nonnegative open readable seekable descriptor, flushed and exclusively held by the caller for the complete operation; never closed or retained by this helper. |
| [in] | offset | Absolute byte offset in [0, INT64_MAX], with offset+bytes <= INT64_MAX. |
| [out] | data | Writable storage for at least bytes bytes; null permitted only for zero bytes. May contain a copied prefix if reading or final position restoration fails. |
| [in] | bytes | Exact byte count; zero still checks/repositions/restores the descriptor. |
| std::runtime_error | Invalid range, failed initial seek/read (including early EOF), or failed final restoration. EINTR reads retry; already copied bytes are not rolled back. |
Saves the original file position, seeks and reads in at most INT_MAX chunks, then attempts to restore the saved offset even after failed reads. A restoration failure is reported, so the original position is not guaranteed on failure. Does not flush a C/HDF5 writer, lock the descriptor, validate source identity or advance simulation. This avoids opening another handle under Windows mandatory file locking.
| void openswmm::io::checkpointSeek | ( | FILE * | f, |
| uint64_t | offset ) |
Position an existing stream at an absolute checkpoint byte offset.
| [in,out] | f | Non-null open seekable stream, borrowed and not closed. |
| [in] | offset | Absolute byte offset in [0, INT64_MAX]; seeking beyond the current end is allowed when supported by the underlying stream. |
| std::runtime_error | The stream or offset is invalid, or seeking fails. |
| std::shared_ptr< OwnedCheckpointFile > openswmm::io::copyCheckpointFile | ( | const std::filesystem::path & | source, |
| uint64_t | bytes, | ||
| const std::filesystem::path & | staging_base, | ||
| int | source_descriptor = -1 ) |
Copy and verify an exact source prefix into a private companion file.
Copy exactly a known prefix; validate the copy again before publication. Exclusive creation and ownership ensure failures cannot remove other files. A supplied descriptor is borrowed from a flushed, exclusively held writer; its position is preserved, avoiding a second handle under mandatory locks.
| [in] | source | Non-symlink regular source file, read from byte zero. |
| [in] | bytes | Prefix length in [1, source file size], no larger than INT64_MAX. |
| [in] | staging_base | Base path for exclusive sibling names ending in .file-part-N; its parent must exist and permit file creation. |
| [in] | source_descriptor | Borrowed seekable descriptor for the same source file, or -1 to open source independently. Caller must flush/exclusively hold a supplied writer; its offset is preserved. The descriptor/file identity is a caller precondition, not independently checked. |
| std::runtime_error | Validation, opening, copying, synchronization, closing, verification or all 32 exclusive reservations fail. Filesystem and allocation exceptions may propagate. Partial owned copies are cleaned up. |
| hid_t openswmm::io::createCheckpointHdf5 | ( | const char * | path, |
| unsigned | flags ) |
Create a checkpoint-compatible HDF5 result file.
Creation disables wall-clock object timestamps for deterministic checkpoint images. Serializes this operation with resultHdf5Mutex, uses the checkpoint VFD on Windows and default HDF5 access on POSIX. Temporary access properties are released before return. Caller must serialize later HDF5 operations and own the returned file lifetime; opening/creating does not retain caller path storage.
| [in] | path | Non-null null-terminated filename, borrowed for the call; UTF-8 on Windows. |
| [in] | flags | H5Fcreate flags, such as H5F_ACC_TRUNC or H5F_ACC_EXCL; determine replacement/exclusive-create behavior. |
|
inline |
Create a dataset without wall-clock object timestamps.
| [in] | location | Borrowed file or group identifier for the new link. |
| [in] | name | Non-null null-terminated dataset path, borrowed for this call. |
| [in] | type | Borrowed HDF5 datatype identifier. |
| [in] | space | Borrowed dataspace defining the dataset shape. |
| [in] | links | Borrowed link-creation properties or H5P_DEFAULT. |
| [in] | creation | Borrowed dataset-creation properties or H5P_DEFAULT; copied before disabling timestamp tracking. |
| [in] | access | Borrowed dataset-access properties or H5P_DEFAULT. |
|
inline |
Create an HDF5 file without wall-clock object timestamps.
| [in] | path | Non-null null-terminated destination filename. |
| [in] | flags | H5Fcreate access flags, such as H5F_ACC_TRUNC or H5F_ACC_EXCL. |
| [in] | creation | Borrowed file-creation properties or H5P_DEFAULT; copied before disabling timestamp tracking. |
| [in] | access | Borrowed file-access properties or H5P_DEFAULT. |
|
inline |
Create a group without wall-clock object timestamps.
| [in] | location | Borrowed file or group identifier for the new link. |
| [in] | name | Non-null null-terminated group path, borrowed for this call. |
| [in] | links | Borrowed link-creation properties or H5P_DEFAULT. |
| [in] | creation | Borrowed group-creation properties or H5P_DEFAULT; copied before disabling timestamp tracking. |
| [in] | access | Borrowed group-access properties or H5P_DEFAULT. |
|
inline |
Open a borrowed native path using platform C stdio.
Windows widens the ASCII mode and invokes _wfopen; POSIX calls fopen. Mode may truncate/create the destination. C-runtime errors use errno; allocations for the Windows mode string may throw.
| [in] | p | Borrowed native filesystem path. |
| [in] | mode | Non-null NUL-terminated ASCII fopen mode; must be valid for the platform C runtime. |
|
inline |
Convert engine path bytes and open a C stdio stream.
Path conversion/allocation exceptions propagate. Opening can create/truncate according to mode.
| [in] | utf8 | Borrowed UTF-8 Windows path or native POSIX path bytes. |
| [in] | mode | Non-null NUL-terminated ASCII stdio mode, passed to fopen_path(). |
|
noexcept |
Recognize platform-neutral absolute-looking path syntax.
Drive-relative C:folder is deliberately classified as absolute-looking here, unlike native Windows filesystem semantics. No filesystem lookup or validity checking.
| [in] | path | Borrowed byte string; no separator normalization is performed. |
| RelativeResult openswmm::io::makeRelative | ( | const std::string & | target_absolute, |
| const std::string & | anchor_dir, | ||
| int | max_up_levels = 16 ) |
Compute a lexical relative token or return a classified absolute fallback.
Pure lexical operation: does not resolve symlinks, check existence or detect POSIX mount boundaries. Recognizes drive/UNC roots across hosts and compares the entire root case-insensitively using C-locale lowercase. Empty anchor returns normalized target with AbsoluteSameVolume for recognized absolute syntax, otherwise Invalid. Relative output uses forward slashes and preserves authored relative geometry. Allocation/encoding exceptions propagate.
| [in] | target_absolute | Borrowed target text expected absolute; an empty target is Invalid. Nonempty relative text is not independently rejected when an anchor exists. |
| [in] | anchor_dir | Borrowed directory token. It is always treated as a directory; no file-type detection or automatic parent extraction occurs. |
| [in] | max_up_levels | Maximum permitted leading parent segments, default 16; negative values force absolute fallback even for zero parent segments. |
| std::string openswmm::io::normaliseSeparators | ( | const std::string & | path | ) |
Normalize separator and dot spelling without resolving parent segments.
Text cleanup only: does not consult files, resolve parent segments or promise native canonical form. Drive/UNC root-shaped strings receive special trailing-slash preservation.
| [in] | path | Borrowed path-like byte string; empty stays empty. |
| hid_t openswmm::io::openCheckpointHdf5 | ( | const char * | path, |
| unsigned | flags ) |
Open a checkpoint-compatible HDF5 result file.
Serializes this operation with resultHdf5Mutex, uses the checkpoint VFD on Windows and default HDF5 access on POSIX. Temporary access properties are released before return. Caller must serialize later HDF5 operations and own the returned file lifetime; opening/creating does not retain caller path storage.
| [in] | path | Non-null null-terminated filename, borrowed for the call; UTF-8 on Windows. |
| [in] | flags | H5Fopen access flags, normally H5F_ACC_RDONLY or H5F_ACC_RDWR. |
| std::string openswmm::io::parentDir | ( | const std::string & | file_path | ) |
Extract a directory token using normalized separator text.
Does not inspect filesystem object type: an actual directory without a trailing separator is treated like a filename. Recognized drive/root prefixes are preserved.
| [in] | file_path | Borrowed token. A trailing slash/backslash explicitly marks a directory; otherwise the final component is treated as a filename. |
|
inline |
Copy a native path into the engine byte-string representation.
No filesystem lookup. Allocation/encoding exceptions propagate; use utf8_path() explicitly before passing byte strings here.
| [in] | p | Borrowed native filesystem path, already constructed using the intended encoding. |
| [in] | generic | True selects generic slash separators, false native formatting. |
|
delete |
The mirror guard: path_utf8() takes a path, never a string.
A std::string or const char* argument would silently construct the fs::path parameter from the NATIVE NARROW encoding — the ANSI code page on Windows — which is issue #7 itself, arrived at through the very helper meant to prevent it, and again visible only on MSVC. Convert explicitly with utf8_path() first if that is genuinely what was meant.
| void openswmm::io::publishCheckpointNoReplace | ( | const std::filesystem::path & | staging, |
| const std::filesystem::path & | destination ) |
Atomically publish a private file/directory without replacing any destination.
Atomically rename a staged checkpoint without replacing a destination.
| [in] | staging | Existing private file or directory to move; must be on a filesystem where the platform's no-replace rename can succeed. |
| [in] | destination | Final path, which must not already exist. |
| std::runtime_error | Publication fails or no supported platform primitive is compiled in. Paths remain caller-owned. |
| std::string openswmm::io::resolveRelative | ( | const std::string & | stored_token, |
| const std::string & | anchor_dir ) |
Join a stored token to a directory anchor using lexical normalization.
No file access, symlink resolution or existence check. The result is absolute only if input syntax or a suitable absolute anchor makes it so. Windows encoding/allocation errors can throw.
| [in] | stored_token | Borrowed path bytes; empty returns empty. Leading slash, alphabetic drive-colon or UNC syntax is considered already absolute. |
| [in] | anchor_dir | Borrowed directory anchor; empty leaves a normalized relative token rather than making it absolute. |
|
inline |
Access the shared recursive lock for result-file HDF5 operations.
|
inline |
Convert borrowed path bytes into an owned native filesystem path.
Windows conversion uses char8_t UTF-8 construction. Allocation/encoding exceptions propagate; POSIX input may contain non-UTF-8 bytes.
| [in] | utf8 | Path bytes: interpreted as UTF-8 on Windows, passed through unchanged on POSIX. |
|
delete |
Passing an fs::path to utf8_path() is always a mistake — refuse it at compile time, on EVERY platform.
The value is already a path; re-encoding it is at best a no-op and at worst the very corruption this header exists to prevent. The reason this needs a deleted overload rather than a code review is that the mistake COMPILES ON POSIX: fs::path::string_type is std::string there, so path converts implicitly to the const std::string& parameter. On Windows string_type is std::wstring, no such conversion exists, and it is a hard error — so a Linux/macOS build and a local -fsyntax-only check both pass and only the MSVC job fails. That cost two Windows CI cycles (b3b1590d → b814bcf8, then again at 92e63366) before this guard existed.
Constrained to match ONLY an actual path: a bare overload taking const fs::path& would make utf8_path("literal") and utf8_path(char_ptr) ambiguous, since converting const char* to std::string and to path are equally good user-defined conversions. A template that matches path exactly wins against the conversion to std::string and loses for everything else, which is precisely the rule we want.