Hot start C API implementation — thin wrappers around HotStartManager. More...

#include "SWMMEngine.hpp"
#include "HotStartManager.hpp"
#include "../plugins/PluginFactory.hpp"
#include "../../../include/openswmm/engine/openswmm_hotstart.h"
#include "../../../include/openswmm/plugin_sdk/IStateIOPlugin.hpp"
#include <cstring>

Include dependency graph for openswmm_hotstart_impl.cpp:

Macros
#define	CHECK_ENGINE(e)

#define	CHECK_HS(hs)

Functions
SWMM_ENGINE_API const char *	swmm_hotstart_last_io_error (void)
	Borrow the built-in hot-start reader/writer diagnostic for this thread.

SWMM_ENGINE_API int	swmm_hotstart_save (SWMM_Engine engine, const char *path)
	Write current simulation state through the native checkpoint or state-IO path.

SWMM_ENGINE_API int	swmm_hotstart_open (const char path, SWMM_HotStart hs)
	Load a native OPENSWMM hot-start file into an independent handle.

SWMM_ENGINE_API int	swmm_hotstart_apply (SWMM_Engine engine, SWMM_HotStart hs)
	Apply record state or queue a complete restart on an initialized engine.

SWMM_ENGINE_API int	swmm_hotstart_set_node_depth (SWMM_HotStart hs, const char *node_id, double depth)
	Edit one stored node depth record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_node_head (SWMM_HotStart hs, const char *node_id, double head)
	Edit one stored node head record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_link_flow (SWMM_HotStart hs, const char *link_id, double flow)
	Edit one stored link flow record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_link_depth (SWMM_HotStart hs, const char *link_id, double depth)
	Edit one stored link depth record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_subcatch_runoff (SWMM_HotStart hs, const char *subcatch_id, double runoff)
	Edit one stored subcatchment runoff record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_get_sim_time (SWMM_HotStart hs, double *sim_time)
	Read the saved elapsed simulation time.

SWMM_ENGINE_API int	swmm_hotstart_get_start_date (SWMM_HotStart hs, double *start_date)
	Read the saving run start calendar date.

SWMM_ENGINE_API int	swmm_hotstart_get_crs (SWMM_HotStart hs, char *buf, int buflen)
	Copy the hot-start header CRS string.

SWMM_ENGINE_API int	swmm_hotstart_node_count (SWMM_HotStart hs)
	Count stored node records in a hot-start handle.

SWMM_ENGINE_API int	swmm_hotstart_link_count (SWMM_HotStart hs)
	Count stored link records in a hot-start handle.

SWMM_ENGINE_API int	swmm_hotstart_warning_count (SWMM_HotStart hs)
	Count warnings retained by the hot-start handle.

SWMM_ENGINE_API const char *	swmm_hotstart_warning (SWMM_HotStart hs, int index)
	Borrow one retained hot-start warning.

SWMM_ENGINE_API int	swmm_hotstart_close (SWMM_HotStart hs)
	Flush dirty record edits and destroy a hot-start handle.

Detailed Description

Hot start C API implementation — thin wrappers around HotStartManager.

Every function declared in include/openswmm/engine/openswmm_hotstart.h is implemented here.

Pattern:

Validate handle (non-null, correct type).
Cast opaque void* → HotStartFile* or SWMMEngine*.
Delegate to HotStartManager static methods.
Return SWMM_OK or an error code.

Note: Must be compiled as C++ (pulls in C++ headers), but exported symbols use C linkage via extern "C".

See also: include/openswmm/engine/openswmm_hotstart.h; HotStartManager.hpp; SWMMEngine.hpp

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

◆ CHECK_ENGINE

#define CHECK_ENGINE ( e )

Value:

    do {                                                                                           \
        if (!(e))                                                                                  \
            return SWMM_ERR_BADHANDLE;                                                             \
    } while (0)

◆ CHECK_HS

#define CHECK_HS ( hs )

Value:

    do {                                                                                           \
        if (!(hs))                                                                                 \
            return SWMM_ERR_BADHANDLE;                                                             \
    } while (0)

Function Documentation

◆ swmm_hotstart_apply()

SWMM_ENGINE_API int swmm_hotstart_apply	(	SWMM_Engine	engine,
		SWMM_HotStart	hs )

Apply record state or queue a complete restart on an initialized engine.

Record-based application matches string IDs, keeps missing target objects unchanged, records missing source objects as warnings and reopens mass-balance initial storage on success. This wrapper passes a no-op warning sink; use swmm_hotstart_warning_count()/warning() rather than assuming a registered engine warning callback fires. Full-engine checkpoint payloads are queued here and restored during subsequent engine start, after owners initialize; queue acceptance is not completed restoration. Record application is not promised atomic on every extension failure.

Parameters

[in]	engine	Non-null INITIALIZED engine whose model and restart owners support the file profile.
[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: SWMM_OK when records apply or a full-engine restart is queued; SWMM_ERR_BADHANDLE for a null handle, SWMM_ERR_LIFECYCLE outside INITIALIZED, or SWMM_ERR_HOTSTART for a refused/incompatible restart.

Here is the call graph for this function:

◆ swmm_hotstart_close()

SWMM_ENGINE_API int swmm_hotstart_close ( SWMM_HotStart hs )

Flush dirty record edits and destroy a hot-start handle.

Unmodified handles do not rewrite the file. Setters mark their records dirty; close attempts to persist those changes to the original path before freeing all storage.

Parameters

[in] hs Caller-owned live hot-start handle, or NULL for a successful no-op. The handle is destroyed even if flush fails; do not retry close or use it afterward.

Returns: SWMM_OK after close/no-op; SWMM_ERR_IO when dirty write-back fails.

Here is the call graph for this function:

◆ swmm_hotstart_get_crs()

SWMM_ENGINE_API int swmm_hotstart_get_crs	(	SWMM_HotStart	hs,
		char *	buf,
		int	buflen )

Copy the hot-start header CRS string.

Returns stored metadata without validating coordinates or compatibility with another model.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[out]	buf	Non-null caller-owned destination; success NUL-terminates and silently truncates to buflen-1 bytes. An absent CRS is an empty string.
[in]	buflen	Positive byte capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_get_sim_time()

SWMM_ENGINE_API int swmm_hotstart_get_sim_time	(	SWMM_HotStart	hs,
		double *	sim_time )

Read the saved elapsed simulation time.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[out]	sim_time	Non-null destination for elapsed seconds since the saving run start calendar date.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_get_start_date()

SWMM_ENGINE_API int swmm_hotstart_get_start_date	(	SWMM_HotStart	hs,
		double *	start_date )

Read the saving run start calendar date.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[out]	start_date	Non-null destination for OADate/SWMM DateTime decimal days since 1899-12-30; no timezone conversion.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_last_io_error()

SWMM_ENGINE_API const char * swmm_hotstart_last_io_error ( void )

Borrow the built-in hot-start reader/writer diagnostic for this thread.

This diagnostic belongs to HotStartManager, not the independent checkpoint diagnostic or every possible state-IO plugin.

Returns: NUL-terminated thread-local string, empty when no detailed IO diagnostic is available. Do not free it; copy before another hot-start IO call on this thread.

Here is the call graph for this function:

◆ swmm_hotstart_link_count()

SWMM_ENGINE_API int swmm_hotstart_link_count ( SWMM_HotStart hs )

Count stored link records in a hot-start handle.

Parameters

[in] hs Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: Stored link-record count, or -1 for null hs.

◆ swmm_hotstart_node_count()

SWMM_ENGINE_API int swmm_hotstart_node_count ( SWMM_HotStart hs )

Count stored node records in a hot-start handle.

A full-engine checkpoint payload need not expose its embedded state as editable record rows.

Parameters

[in] hs Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: Stored node-record count, or -1 for null hs.

◆ swmm_hotstart_open()

SWMM_ENGINE_API int swmm_hotstart_open	(	const char *	path,
		SWMM_HotStart *	hs )

Load a native OPENSWMM hot-start file into an independent handle.

Reads the file into owned in-memory records and restart extensions; no engine handle is retained. Release with swmm_hotstart_close(). This reader is distinct from the model-bound legacy USE HOTSTART loader.

Parameters

[in]	path	Non-null, nonempty NUL-terminated native hot-start path; borrowed for the call.
[out]	hs	Non-null output slot. Set to NULL before path/read validation, then to a newly allocated caller-owned handle on success. A previous handle in this variable is not freed.

Returns: SWMM_OK; SWMM_ERR_BADPARAM for null output or null/empty path; SWMM_ERR_HOTSTART when native magic/version/checksum/content validation fails.

Here is the call graph for this function:

◆ swmm_hotstart_save()

SWMM_ENGINE_API int swmm_hotstart_save	(	SWMM_Engine	engine,
		const char *	path )

Write current simulation state through the native checkpoint or state-IO path.

A heat model with a qualified attached full-engine checkpoint uses its accepted native restart. Otherwise state-IO plugins are tried in order until one succeeds, with a built-in record-format fallback when no state plugin is registered. Record files match objects by ID; full-engine checkpoints require matching model/provider/runtime state and are restored at a subsequent start. This is not the exclusive new-path checkpoint API and does not promise no-replace publication.

Parameters

[in]	engine	Non-null engine in RUNNING or ENDED; exclusive access is required.
[in]	path	Non-null, nonempty NUL-terminated destination path, borrowed for the synchronous call.

Returns: SWMM_OK on successful write; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null/empty path, SWMM_ERR_LIFECYCLE outside RUNNING/ENDED, or SWMM_ERR_HOTSTART on checkpoint/state-writer failure.

Here is the call graph for this function:

◆ swmm_hotstart_set_link_depth()

SWMM_ENGINE_API int swmm_hotstart_set_link_depth	(	SWMM_HotStart	hs,
		const char *	link_id,
		double	depth )

Edit one stored link depth record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	link_id	Non-null NUL-terminated link ID, matched exactly/case-sensitively against stored records.
[in]	depth	New depth in internal feet (ft); assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_link_flow()

SWMM_ENGINE_API int swmm_hotstart_set_link_flow	(	SWMM_HotStart	hs,
		const char *	link_id,
		double	flow )

Edit one stored link flow record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	link_id	Non-null NUL-terminated link ID, matched exactly/case-sensitively against stored records.
[in]	flow	New flow in internal cubic feet per second (ft3/s), signed in stored link orientation; assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_node_depth()

SWMM_ENGINE_API int swmm_hotstart_set_node_depth	(	SWMM_HotStart	hs,
		const char *	node_id,
		double	depth )

Edit one stored node depth record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	node_id	Non-null NUL-terminated node ID, matched exactly/case-sensitively against stored records.
[in]	depth	New depth in internal feet (ft), regardless of project display units; assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_node_head()

SWMM_ENGINE_API int swmm_hotstart_set_node_head	(	SWMM_HotStart	hs,
		const char *	node_id,
		double	head )

Edit one stored node head record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	node_id	Non-null NUL-terminated node ID, matched exactly/case-sensitively against stored records.
[in]	head	New head in internal datum feet (ft); assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_subcatch_runoff()

SWMM_ENGINE_API int swmm_hotstart_set_subcatch_runoff	(	SWMM_HotStart	hs,
		const char *	subcatch_id,
		double	runoff )

Edit one stored subcatchment runoff record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	subcatch_id	Non-null NUL-terminated subcatchment ID, matched exactly/case-sensitively against stored records.
[in]	runoff	New runoff in internal cubic feet per second (ft3/s); assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_warning()

SWMM_ENGINE_API const char * swmm_hotstart_warning	(	SWMM_HotStart	hs,
		int	index )

Borrow one retained hot-start warning.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	index	Zero-based index in [0,swmm_hotstart_warning_count(hs)).

Returns: Handle-owned NUL-terminated warning string, or NULL for null hs/out-of-range index. Never free it; copy before applying again or closing hs.

◆ swmm_hotstart_warning_count()

SWMM_ENGINE_API int swmm_hotstart_warning_count ( SWMM_HotStart hs )

Count warnings retained by the hot-start handle.

Record-based apply clears/repopulates this list; it can contain missing-object and restart-profile diagnostics. The full-checkpoint queue path does not promise to refresh this list.

Parameters

[in] hs Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: Warning count, or 0 for null hs.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CHECK_ENGINE

◆ CHECK_HS

Function Documentation

◆ swmm_hotstart_apply()

◆ swmm_hotstart_close()

◆ swmm_hotstart_get_crs()

◆ swmm_hotstart_get_sim_time()

◆ swmm_hotstart_get_start_date()

◆ swmm_hotstart_last_io_error()

◆ swmm_hotstart_link_count()

◆ swmm_hotstart_node_count()

◆ swmm_hotstart_open()

◆ swmm_hotstart_save()

◆ swmm_hotstart_set_link_depth()

◆ swmm_hotstart_set_link_flow()

◆ swmm_hotstart_set_node_depth()

◆ swmm_hotstart_set_node_head()

◆ swmm_hotstart_set_subcatch_runoff()

◆ swmm_hotstart_warning()

◆ swmm_hotstart_warning_count()