openswmm_checkpoint.h File Reference

Public C API for creating, inspecting, and restoring simulation checkpoints. More...

#include "openswmm_engine.h"
#include <stddef.h>

Include dependency graph for openswmm_checkpoint.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SWMM_CheckpointSessionOptions

Macros
#define	SWMM_CHECKPOINT_INSPECTION   (1UL << 0)
#define	SWMM_CHECKPOINT_RESTORE   (1UL << 1)
#define	SWMM_CHECKPOINT_SAVE_NEW   (1UL << 2)
#define	SWMM_CHECKPOINT_BINARY_PROFILE   (1UL << 3)
#define	SWMM_CHECKPOINT_SURFACE_PROFILE   (1UL << 4)
#define	SWMM_CHECKPOINT_SOURCE_STREAM   (1UL << 5)
#define	SWMM_CHECKPOINT_FILE_PROFILE   (1UL << 6)
#define	SWMM_CHECKPOINT_BUNDLE_EXPORT   (1UL << 7)
#define	SWMM_CHECKPOINT_SESSION_BUILDER   (1UL << 8)
#define	SWMM_CHECKPOINT_SESSION_ATTACHED   (1UL << 0)
#define	SWMM_CHECKPOINT_SESSION_BOUNDARY   (1UL << 1)
#define	SWMM_CHECKPOINT_SESSION_FRESH   (1UL << 2)
#define	SWMM_CHECKPOINT_SESSION_MANAGED   (1UL << 3)
#define	SWMM_CHECKPOINT_OUTPUT_NONE   0
#define	SWMM_CHECKPOINT_OUTPUT_BINARY   1
#define	SWMM_CHECKPOINT_OUTPUT_MESH   2
#define	SWMM_CHECKPOINT_OUTPUT_COMBINED   3
#define	SWMM_CHECKPOINT_OUTPUT_FILES   4

Typedefs
typedef struct SWMM_CheckpointSessionOptions	SWMM_CheckpointSessionOptions
typedef void *	SWMM_CheckpointInspection

Functions
SWMM_ENGINE_API int	swmm_checkpoint_start_session (SWMM_Engine engine, const SWMM_CheckpointSessionOptions *options)
	Initialize and attach a managed checkpoint session at its initial boundary.
SWMM_ENGINE_API int	swmm_checkpoint_capabilities (SWMM_Engine engine, unsigned long *flags)
	Query checkpoint features compiled into this backend.
SWMM_ENGINE_API int	swmm_checkpoint_session_status (SWMM_Engine engine, unsigned long *flags)
	Read the current checkpoint attachment and boundary hints.
SWMM_ENGINE_API int	swmm_checkpoint_inspect (SWMM_Engine engine, const char *path, SWMM_CheckpointInspection *snapshot)
	Validate a checkpoint against a fresh session and return independent metadata.
SWMM_ENGINE_API 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.
SWMM_ENGINE_API void	swmm_checkpoint_inspection_destroy (SWMM_CheckpointInspection snapshot)
	Release an inspection snapshot independently of engine lifetime.
SWMM_ENGINE_API int	swmm_checkpoint_save (SWMM_Engine engine, const char *new_path)
	Publish a new checkpoint exclusively at an accepted session boundary.
SWMM_ENGINE_API int	swmm_checkpoint_restore (SWMM_Engine engine, const char *path)
	Restore a compatible checkpoint into an explicitly prepared fresh session.
SWMM_ENGINE_API int	swmm_checkpoint_export_bundle (const char *path, const char *new_folder)
	Package an existing file-backed checkpoint in a new exclusive directory.
SWMM_ENGINE_API const char *	swmm_checkpoint_last_error_msg (void)
	Borrow the diagnostic from the last checkpoint operation on this thread.

Detailed Description

Public C API for creating, inspecting, and restoring 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

Macro Definition Documentation

SWMM_CHECKPOINT_BINARY_PROFILE

#define SWMM_CHECKPOINT_BINARY_PROFILE   (1UL << 3)

SWMM_CHECKPOINT_BUNDLE_EXPORT

#define SWMM_CHECKPOINT_BUNDLE_EXPORT   (1UL << 7)

SWMM_CHECKPOINT_FILE_PROFILE

#define SWMM_CHECKPOINT_FILE_PROFILE   (1UL << 6)

SWMM_CHECKPOINT_INSPECTION

#define SWMM_CHECKPOINT_INSPECTION   (1UL << 0)

SWMM_CHECKPOINT_OUTPUT_BINARY

#define SWMM_CHECKPOINT_OUTPUT_BINARY   1

SWMM_CHECKPOINT_OUTPUT_COMBINED

#define SWMM_CHECKPOINT_OUTPUT_COMBINED   3

SWMM_CHECKPOINT_OUTPUT_FILES

#define SWMM_CHECKPOINT_OUTPUT_FILES   4

SWMM_CHECKPOINT_OUTPUT_MESH

#define SWMM_CHECKPOINT_OUTPUT_MESH   2

SWMM_CHECKPOINT_OUTPUT_NONE

#define SWMM_CHECKPOINT_OUTPUT_NONE   0

SWMM_CHECKPOINT_RESTORE

#define SWMM_CHECKPOINT_RESTORE   (1UL << 1)

SWMM_CHECKPOINT_SAVE_NEW

#define SWMM_CHECKPOINT_SAVE_NEW   (1UL << 2)

SWMM_CHECKPOINT_SESSION_ATTACHED

#define SWMM_CHECKPOINT_SESSION_ATTACHED   (1UL << 0)

SWMM_CHECKPOINT_SESSION_BOUNDARY

#define SWMM_CHECKPOINT_SESSION_BOUNDARY   (1UL << 1)

SWMM_CHECKPOINT_SESSION_BUILDER

#define SWMM_CHECKPOINT_SESSION_BUILDER   (1UL << 8)

SWMM_CHECKPOINT_SESSION_FRESH

#define SWMM_CHECKPOINT_SESSION_FRESH   (1UL << 2)

SWMM_CHECKPOINT_SESSION_MANAGED

#define SWMM_CHECKPOINT_SESSION_MANAGED   (1UL << 3)

SWMM_CHECKPOINT_SOURCE_STREAM

#define SWMM_CHECKPOINT_SOURCE_STREAM   (1UL << 5)

SWMM_CHECKPOINT_SURFACE_PROFILE

#define SWMM_CHECKPOINT_SURFACE_PROFILE   (1UL << 4)

Typedef Documentation

SWMM_CheckpointInspection

typedef void* SWMM_CheckpointInspection

SWMM_CheckpointSessionOptions

typedef struct SWMM_CheckpointSessionOptions SWMM_CheckpointSessionOptions

Function Documentation

swmm_checkpoint_capabilities()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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()

SWMM_ENGINE_API 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: