openswmm_checkpoint_impl.cpp File Reference

Public C API implementation for simulation checkpoints. More...

#include <openswmm/engine/openswmm_checkpoint.h>
#include "SWMMEngine.hpp"
#include "CheckpointInspection.hpp"
#include "../io/CheckpointDirectory.hpp"
#include <algorithm>
#include <cstring>
#include <exception>
#include <memory>
#include <new>
#include <string_view>

Include dependency graph for openswmm_checkpoint_impl.cpp:

Functions
int	swmm_checkpoint_capabilities (SWMM_Engine handle, unsigned long *flags)
	Query checkpoint features compiled into this backend.
int	swmm_checkpoint_session_status (SWMM_Engine handle, unsigned long *flags)
	Read the current checkpoint attachment and boundary hints.
int	swmm_checkpoint_start_session (SWMM_Engine handle, const SWMM_CheckpointSessionOptions *options)
	Initialize and attach a managed checkpoint session at its initial boundary.
int	swmm_checkpoint_inspect (SWMM_Engine handle, const char *path, SWMM_CheckpointInspection *snapshot)
	Validate a checkpoint against a fresh session and return independent metadata.
int	swmm_checkpoint_inspection_json (SWMM_CheckpointInspection handle, char *out, size_t capacity, size_t *required)
	Copy inspection metadata as a complete NUL-terminated UTF-8 JSON document.
void	swmm_checkpoint_inspection_destroy (SWMM_CheckpointInspection handle)
	Release an inspection snapshot independently of engine lifetime.
int	swmm_checkpoint_save (SWMM_Engine handle, const char *path)
	Publish a new checkpoint exclusively at an accepted session boundary.
int	swmm_checkpoint_restore (SWMM_Engine handle, const char *path)
	Restore a compatible checkpoint into an explicitly prepared fresh session.
int	swmm_checkpoint_export_bundle (const char *path, const char *folder)
	Package an existing file-backed checkpoint in a new exclusive directory.
const char *	swmm_checkpoint_last_error_msg (void)
	Borrow the diagnostic from the last checkpoint operation on this thread.

Detailed Description

Public C API implementation for simulation checkpoints.

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License

Apache-2.0

Function Documentation

swmm_checkpoint_capabilities()

int swmm_checkpoint_capabilities	(	SWMM_Engine	engine,
		unsigned long *	flags )

Query checkpoint features compiled into this backend.

Capabilities describe backend support, not compatibility of a particular model or session.

Parameters

[in]	engine	Non-null live engine handle; no prepared checkpoint session is required.
[out]	flags	Non-null destination for the bitwise OR of supported SWMM_CHECKPOINT_* feature flags. Written only on success.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null flags.

Here is the call graph for this function:

swmm_checkpoint_export_bundle()

int swmm_checkpoint_export_bundle	(	const char *	path,
		const char *	new_folder )

Package an existing file-backed checkpoint in a new exclusive directory.

Does not need an engine handle or certify model/provider compatibility. External inputs remain necessary.

Parameters

[in]	path	Nonempty NUL-terminated UTF-8 source checkpoint path.
[in]	new_folder	Nonempty NUL-terminated UTF-8 destination folder that must not already exist.

Returns

SWMM_OK on successful export; SWMM_ERR_BADPARAM for invalid paths, SWMM_ERR_LIFECYCLE when the build lacks file-backed bundle/exclusive-publication support, SWMM_ERR_IO for packaging refusal, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions.

Here is the call graph for this function:

swmm_checkpoint_inspect()

int swmm_checkpoint_inspect	(	SWMM_Engine	engine,
		const char *	path,
		SWMM_CheckpointInspection *	snapshot )

Validate a checkpoint against a fresh session and return independent metadata.

Inspection may perform substantial synchronous IO; it cannot be interrupted and does not adopt checkpoint state. The returned snapshot survives engine close/destruction and must be released with swmm_checkpoint_inspection_destroy(). Restore rechecks publication eligibility.

Parameters

[in]	engine	Non-null engine attached to a matching, explicitly prepared fresh checkpoint session.
[in]	path	Nonempty NUL-terminated UTF-8 checkpoint path, borrowed for the synchronous call.
[out]	snapshot	Non-null destination for a newly allocated immutable inspection handle. Preserved on failure; a previous handle is not freed when replaced.

Returns

SWMM_OK on success; SWMM_ERR_LIFECYCLE for a session that is not fresh/prepared, SWMM_ERR_BADHANDLE for a null engine, SWMM_ERR_BADPARAM for invalid path/output, SWMM_ERR_IO for validation/IO refusal, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions.

Here is the call graph for this function:

swmm_checkpoint_inspection_destroy()

void swmm_checkpoint_inspection_destroy

(

SWMM_CheckpointInspection

snapshot

)

Release an inspection snapshot independently of engine lifetime.

Does not clear the thread-local checkpoint diagnostic.

Parameters

[in]

snapshot

Snapshot owned by the caller, or NULL for a no-op. Every non-null handle must be destroyed exactly once; do not use it afterward.

swmm_checkpoint_inspection_json()

int swmm_checkpoint_inspection_json	(	SWMM_CheckpointInspection	snapshot,
		char *	utf8,
		size_t	capacity,
		size_t *	required )

Copy inspection metadata as a complete NUL-terminated UTF-8 JSON document.

Schema 1 uses raw engine calendar dates and seconds, null optional fields and decimal strings for uint64 counts/bytes/sequences. A driver update of -1 means exhausted; equality to engine_seconds means due now. Metadata does not certify adapter availability.

Parameters

[in]	snapshot	Live inspection handle returned by swmm_checkpoint_inspect(); do not destroy concurrently.
[out]	utf8	Caller-owned destination of capacity bytes, or NULL with capacity=0 to query the required size. No bytes are written when too small.
[in]	capacity	Destination capacity in bytes, including space for the terminating NUL.
[out]	required	Non-null destination for required bytes INCLUDING the terminating NUL. Updated for a size query or short buffer; preserved for invalid handle/arguments.

Returns

SWMM_OK after a size query or full copy; SWMM_ERR_BADHANDLE for null snapshot; SWMM_ERR_BADPARAM for null required, NULL buffer with nonzero capacity, or insufficient capacity.

swmm_checkpoint_last_error_msg()

const char * swmm_checkpoint_last_error_msg

(

void

)

Borrow the diagnostic from the last checkpoint operation on this thread.

The next checkpoint operation clears/overwrites the diagnostic; this getter and inspection destruction do not. The buffer survives engine destruction, is separate from simulation errors, and may truncate long messages.

Returns

Pointer to engine-independent thread-local NUL-terminated storage; empty when the last checkpoint operation succeeded. Never free it; copy it before another checkpoint operation or leaving the thread.

swmm_checkpoint_restore()

int swmm_checkpoint_restore	(	SWMM_Engine	engine,
		const char *	path )

Restore a compatible checkpoint into an explicitly prepared fresh session.

Does not prepare the required session. All engine operations require exclusive access on the owning thread; an earlier successful inspection does not bypass restore validation.

Parameters

[in]	engine	Non-null engine attached to a matching fresh checkpoint session, including source, driver and output ownership.
[in]	path	Nonempty NUL-terminated UTF-8 checkpoint path, borrowed for this synchronous call.

Returns

SWMM_OK after restoration; SWMM_ERR_BADHANDLE/BADPARAM for invalid handle/path, SWMM_ERR_LIFECYCLE for a session that is not fresh/prepared, SWMM_ERR_IO for compatibility/IO refusal, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions.

swmm_checkpoint_save()

int swmm_checkpoint_save	(	SWMM_Engine	engine,
		const char *	new_path )

Publish a new checkpoint exclusively at an accepted session boundary.

Retains successful companions and older checkpoints. Recording/save failure does not roll back previously accepted physics; the caller owns its private workspace and cleanup.

Parameters

[in]	engine	Non-null engine attached at an accepted checkpoint session boundary.
[in]	new_path	Nonempty NUL-terminated UTF-8 destination. It must not exist; files, directories, symlinks and concurrent creation are refused.

Returns

SWMM_OK after successful publication; SWMM_ERR_BADHANDLE/BADPARAM for invalid handle/path, SWMM_ERR_LIFECYCLE for an unprepared boundary or unavailable exclusive publication, SWMM_ERR_IO for a save refusal, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions.

Here is the call graph for this function:

swmm_checkpoint_session_status()

int swmm_checkpoint_session_status	(	SWMM_Engine	engine,
		unsigned long *	flags )

Read the current checkpoint attachment and boundary hints.

These inexpensive hints do not replace full validation by inspect, save or restore.

Parameters

[in]	engine	Non-null live engine handle.
[out]	flags	Non-null destination for SWMM_CHECKPOINT_SESSION_* bits; written only on success.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null flags.

swmm_checkpoint_start_session()

int swmm_checkpoint_start_session	(	SWMM_Engine	engine,
		const SWMM_CheckpointSessionOptions *	options )

Initialize and attach a managed checkpoint session at its initial boundary.

See the profile and fresh-destination requirements above. A preflight refusal preserves OPENED; a failure after initialization closes the engine. Retrieve the operation diagnostic with swmm_checkpoint_last_error_msg().

Parameters

[in]	engine	Non-null engine in SWMM_STATE_OPENED; requires exclusive access on its owning thread.
[in]	options	Non-null options with struct_size >= sizeof(SWMM_CheckpointSessionOptions), schema_version=1, a SWMM_CHECKPOINT_OUTPUT_* profile and detailed_source_intervals equal to 0 or 1. Strings are borrowed for this synchronous call and copied internally.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine, SWMM_ERR_BADPARAM for invalid schema/options or UTF-8, SWMM_ERR_LIFECYCLE for an invalid state or unavailable build profile, or SWMM_ERR_IO for a profile/preparation refusal. Allocation and unexpected exceptions map to SWMM_ERR_NOMEM and SWMM_ERR_INTERNAL.

Here is the call graph for this function: