Declares the C ABI base-subscriber interface. More...

Typedefs
typedef struct apo_subscriber	apo_subscriber
	Represents a borrowed base-subscriber view in the C ABI.

Functions
apo_status	apo_subscriber_set_report_frequency (apo_subscriber *subscriber, const int report_frequency)
	Sets a subscriber's reporting interval.

apo_status	apo_subscriber_get_report_frequency (int report_frequency, const apo_subscriber subscriber)
	Returns a subscriber's reporting interval.

Detailed Description

Declares the C ABI base-subscriber interface.

Typedef Documentation

◆ apo_subscriber

typedef struct apo_subscriber apo_subscriber

Represents a borrowed base-subscriber view in the C ABI.

Concrete subscriber conversion functions, such as apo_dcd_subscriber_as_subscriber, return this view. The view does not own the concrete handle and has no destroy function. It remains valid only while the concrete C handle that contains it remains alive.

All functions in this header borrow the view for one call and do not retain the C pointer. Native integrator subscription can retain the underlying C++ subscriber object, but it does not extend the lifetime of this embedded C view. Preserve the concrete C handle whenever the view will be used again.

Passing NULL, a dangling view, a view whose concrete owner was destroyed, or a foreign pointer is invalid. Do not overlap mutation, destruction of the concrete owner, or integrator attachment operations on the same object from multiple threads.

Status-returning calls clear the calling thread's previous diagnostic at entry. On failure, call apo_last_error immediately on the same thread. The returned diagnostic pointer is borrowed and is invalidated by the next diagnostic-changing C ABI call on that thread.

See also: subscriber

Function Documentation

◆ apo_subscriber_get_report_frequency()

apo_status apo_subscriber_get_report_frequency	(	int *	report_frequency,
		const apo_subscriber *	subscriber
	)

Returns a subscriber's reporting interval.

Parameters

[out]	report_frequency	Non-`NULL` output pointer receiving a positive, dimensionless step count on success. The function does not initialize this location before validating the handle and pointer.
[in]	subscriber	Borrowed live base view. The pointer may not be `NULL` and is not retained by this call.

Return values

APO_STATUS_OK	The current interval was written to `*report_frequency`.
APO_STATUS_INVALID_ARGUMENT	`subscriber` is `NULL`, its native object is absent, or `report_frequency` is `NULL`.
APO_STATUS_RUNTIME_ERROR	An unexpected standard or nonstandard C++ exception crossed the C ABI boundary.

Postcondition: On failure, a valid report_frequency location retains its previous contents.

Note: The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_subscriber_set_report_frequency()

apo_status apo_subscriber_set_report_frequency	(	apo_subscriber *	subscriber,
		const int	report_frequency
	)

Sets a subscriber's reporting interval.