apoCHARMM 1.0.0
High-performance molecular dynamics simulations on GPUs
 
Loading...
Searching...
No Matches
Typedefs | Functions
RestartSubscriber.h File Reference

Declares the C ABI restart subscriber interface. More...

Typedefs

typedef struct apo_restart_subscriber apo_restart_subscriber
 Represents an owned CHARMM-style restart writer in the C ABI.
 

Functions

apo_status apo_restart_subscriber_create (apo_restart_subscriber **out, const char *path)
 Creates a restart writer with the default 1000-step interval.
 
apo_status apo_restart_subscriber_create_with_report_frequency (apo_restart_subscriber **out, const char *path, const int report_frequency)
 Creates a restart writer with an explicit reporting interval.
 
void apo_restart_subscriber_destroy (apo_restart_subscriber *subscriber)
 Destroys an owned restart-subscriber handle.
 
apo_status apo_restart_subscriber_as_subscriber (apo_subscriber **out, apo_restart_subscriber *subscriber)
 Returns the borrowed base-subscriber view of a restart handle.
 

Detailed Description

Declares the C ABI restart subscriber interface.

Typedef Documentation

◆ apo_restart_subscriber

typedef struct apo_restart_subscriber apo_restart_subscriber

Represents an owned CHARMM-style restart writer in the C ABI.

A successful constructor returns a newly owned handle whose text output file has already been created or truncated. Release it exactly once with apo_restart_subscriber_destroy. The handle can provide a borrowed apo_subscriber view for frequency changes and integrator attachment.

Updates occur indirectly during integrator propagation and replace the file with current context and supported-integrator state. Box lengths and coordinates use angstroms, context velocities use angstroms per AKMA time unit, and average temperature uses kelvin.

Do not overlap destruction, subscription, propagation, or frequency changes involving the same handle from multiple threads.

See also
RestartSubscriber
subscriber

Function Documentation

◆ apo_restart_subscriber_as_subscriber()

apo_status apo_restart_subscriber_as_subscriber ( apo_subscriber **  out,
apo_restart_subscriber *  subscriber 
)

Returns the borrowed base-subscriber view of a restart handle.

Parameters
[out]outNon-NULL output pointer. The function stores NULL before validating subscriber, then stores a borrowed pointer on success.
[in]subscriberBorrowed live restart handle. The pointer may not be NULL and is not retained by this call.
Return values
APO_STATUS_OKA borrowed base view was written to *out.
APO_STATUS_INVALID_ARGUMENTout is NULL, subscriber is NULL, or the handle contains no native restart object.
APO_STATUS_RUNTIME_ERRORAn unexpected standard or nonstandard C++ exception crossed the C ABI boundary.
Postcondition
On failure after a valid out pointer is accepted, *out == NULL.
Note
The returned pointer is valid only while subscriber remains alive. It must not be destroyed separately.
The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_restart_subscriber_create()

apo_status apo_restart_subscriber_create ( apo_restart_subscriber **  out,
const char *  path 
)

Creates a restart writer with the default 1000-step interval.

Parameters
[out]outNon-NULL output pointer. The function stores NULL before validating path or constructing the writer, then stores a newly owned handle on success.
[in]pathNon-NULL, null-terminated filesystem path borrowed for the call and copied by the native subscriber. The string must be nonempty. When the resulting native path has a nonempty parent path, that parent path must exist.
Return values
APO_STATUS_OKA newly owned handle was written to *out and the file was created or truncated.
APO_STATUS_INVALID_ARGUMENTout is NULL, path is NULL, the path is empty, or its checked parent path does not exist.
APO_STATUS_RUNTIME_ERRORThe file could not be opened, native handle or object allocation failed, or another unexpected C++ exception crossed the boundary.
Postcondition
On failure after a valid out pointer is accepted, *out == NULL.
Note
The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_restart_subscriber_create_with_report_frequency()

apo_status apo_restart_subscriber_create_with_report_frequency ( apo_restart_subscriber **  out,
const char *  path,
const int  report_frequency 
)

Creates a restart writer with an explicit reporting interval.

Parameters
[out]outNon-NULL output pointer. The function stores NULL before validating inputs or constructing the writer, then stores a newly owned handle on success.
[in]pathNon-NULL, null-terminated filesystem path borrowed for the call and copied by the native subscriber. The string must be nonempty; when it contains /, its nonempty parent path must exist.
[in]report_frequencyPositive, dimensionless number of propagated steps between restart replacements.
Return values
APO_STATUS_OKA newly owned handle was written to *out and the file was created or truncated.
APO_STATUS_INVALID_ARGUMENTout is NULL, path is NULL, the path is empty, its checked parent path does not exist, or report_frequency is not positive.
APO_STATUS_RUNTIME_ERRORThe file could not be opened, native handle or object allocation failed, or another unexpected C++ exception crossed the boundary.
Postcondition
On failure after a valid out pointer is accepted, *out == NULL.
Note
The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_restart_subscriber_destroy()

void apo_restart_subscriber_destroy ( apo_restart_subscriber *  subscriber)

Destroys an owned restart-subscriber handle.

Parameters
[in]subscriberOwned handle to release. NULL is accepted and is a no-op. A non-NULL pointer and every borrowed base view obtained from it are invalid after this call returns.
Postcondition
No C++ exception escapes the C ABI boundary.
Note
Normal destruction preserves the calling thread's existing apo_last_error diagnostic. An internal destruction failure cannot be returned by this void API and may replace that diagnostic.
Warning
Destroy the handle exactly once. Native integrator ownership of the C++ subscriber does not keep this C handle or its embedded base view alive.