DcdSubscriber.h File Reference

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

Typedefs
typedef struct apo_dcd_subscriber	apo_dcd_subscriber
	Represents an owned CHARMM DCD writer in the C ABI.

Functions
apo_status	apo_dcd_subscriber_create (apo_dcd_subscriber **out, const char *path)
	Creates a DCD writer with the default 1000-step interval.
apo_status	apo_dcd_subscriber_create_with_report_frequency (apo_dcd_subscriber **out, const char *path, const int report_frequency)
	Creates a DCD writer with an explicit reporting interval.
void	apo_dcd_subscriber_destroy (apo_dcd_subscriber *subscriber)
	Destroys an owned DCD-subscriber handle.
apo_status	apo_dcd_subscriber_as_subscriber (apo_subscriber **out, apo_dcd_subscriber *subscriber)
	Returns the borrowed base-subscriber view of a DCD handle.

Detailed Description

Declares the C ABI DCD subscriber interface.

Typedef Documentation

apo_dcd_subscriber

typedef struct apo_dcd_subscriber apo_dcd_subscriber

Represents an owned CHARMM DCD writer in the C ABI.

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

Native coordinate frames contain single-precision X, Y, and Z coordinates in atom order and box lengths in angstroms. Updates are requested indirectly by subscribing the base view to an integrator and propagating dynamics.

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

See also

DcdSubscriber

subscriber

Function Documentation

apo_dcd_subscriber_as_subscriber()

apo_status apo_dcd_subscriber_as_subscriber	(	apo_subscriber **	out,
		apo_dcd_subscriber *	subscriber
	)

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

Parameters

[out]	out	Non-NULL output pointer. The function stores NULL before validating subscriber, then stores a borrowed pointer on success.
[in]	subscriber	Borrowed live DCD handle. The pointer may not be NULL and is not retained by this call.

Return values

APO_STATUS_OK	A borrowed base view was written to *out.
APO_STATUS_INVALID_ARGUMENT	out is NULL, subscriber is NULL, or the handle contains no native DCD object.
APO_STATUS_RUNTIME_ERROR	An 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_dcd_subscriber_create()

apo_status apo_dcd_subscriber_create	(	apo_dcd_subscriber **	out,
		const char *	path
	)

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

Parameters

[out]	out	Non-NULL output pointer. The function stores NULL before validating path or constructing the writer, then stores a newly owned handle on success.
[in]	path	Non-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_OK	A newly owned handle was written to *out and the file was created or truncated.
APO_STATUS_INVALID_ARGUMENT	out is NULL, path is NULL, the path is empty, or its checked parent path does not exist.
APO_STATUS_RUNTIME_ERROR	The 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_dcd_subscriber_create_with_report_frequency()

apo_status apo_dcd_subscriber_create_with_report_frequency	(	apo_dcd_subscriber **	out,
		const char *	path,
		const int	report_frequency
	)

Creates a DCD writer with an explicit reporting interval.

Parameters

[out]	out	Non-NULL output pointer. The function stores NULL before validating inputs or constructing the writer, then stores a newly owned handle on success.
[in]	path	Non-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_frequency	Positive, dimensionless number of propagated steps between DCD frames.

Return values

APO_STATUS_OK	A newly owned handle was written to *out and the file was created or truncated.
APO_STATUS_INVALID_ARGUMENT	out 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_ERROR	The 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_dcd_subscriber_destroy()

void apo_dcd_subscriber_destroy

(

apo_dcd_subscriber *

subscriber

)

Destroys an owned DCD-subscriber handle.

Parameters

[in]

subscriber

Owned 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.