Struct rusteron_archive::AeronArchive

source ·

pub struct AeronArchive { /* private fields */ }

Implementations§

source §

impl AeronArchive

source

pub fn new_zeroed() -> Result<Self, AeronCError>

source

pub fn close(&self) -> Result<i32, AeronCError>

Close the connection to the Aeron Archive and free up associated resources.

source

pub fn get_archive_context(&self) -> AeronArchiveContext

Retrieve the underlying AeronArchiveContext used to configure the provided AeronArchive.

source

pub fn get_and_own_archive_context(&self) -> AeronArchiveContext

Retrieve the underlying AeronArchiveContext used to configure the provided AeronArchive.

Additionally, calling this function transfers ownership of the returned AeronArchiveContext to the caller. i.e. it is now the the caller’s responsibility to close the context. This is useful when wrapping the C library in other, higher level languages.

source

pub fn get_archive_id(&self) -> i64

Retrieve the archive id of the connected Aeron Archive.

source

pub fn get_control_response_subscription(&self) -> AeronSubscription

Retrieve the underlying AeronSubscription used for reading responses from the connected Aeron Archive.

source

pub fn get_and_own_control_response_subscription(&self) -> AeronSubscription

Retrieve the underlying AeronSubscription used for reading responses from the connected Aeron Archive.

Additionally, calling this function transfers ownership of the returned AeronSubscription to the caller. i.e. it is now the caller’s responsibility to close the subscription. This is useful when wrapping the C library in other, high level languages.

source

pub fn control_session_id(&self) -> i64

source

pub fn poll_for_recording_signals(&self) -> Result<i32, AeronCError>

Poll for recording signals, dispatching them to the configured aeron_archive_recording_signal_consumer_func_t in the context

§Return

count_p out param that indicates the number of recording signals dispatched.

source

pub fn poll_for_error_response( &self, buffer: *mut c_char, buffer_length: usize, ) -> Result<i32, AeronCError>

Poll the response stream once for an error. If another message is present then it will be skipped over, so only call when not expecting another response.

§Return

0 if an error sent from the Aeron Archive is found, in which case, the provided buffer contains the error message. If there was no error, the buffer will be an empty string.

-1 if an error occurs while attempting to read from the subscription.

source

pub fn check_for_error_response(&self) -> Result<i32, AeronCError>

Poll the response stream once for an error.

§Return

0 if no error is found OR if an error is found but an error handler is specified in the context.

-1 if an error is found and no error handler is specified. The error message can be retrieved by calling aeron_errmsg()

source

pub fn start_recording( &self, recording_channel: &str, recording_stream_id: i32, source_location: aeron_archive_source_location_t, auto_stop: bool, ) -> Result<i64, AeronCError>

Start recording a channel/stream pairing.

Channels that include session id parameters are considered different than channels without session ids. If a publication matches both a session id specific channel recording and a non session id specific recording, it will be recorded twice.

§Return

subscription_id_p out param set to the subscription id of the recording

§Parameters

recording_channel the channel of the publication to be recorded
recording_stream_id the stream id of the publication to be recorded
source_location the source location of the publication to be recorded
auto_stop should the recording be automatically stopped when complete

source

pub fn get_recording_position( &self, recording_id: i64, ) -> Result<i64, AeronCError>

Fetch the position recorded for the specified recording.

§Return

recording_position_p out param set to the recording position of the specified recording

§Parameters

recording_id the active recording id

source

pub fn get_start_position(&self, recording_id: i64) -> Result<i64, AeronCError>

Fetch the start position for the specified recording.

§Return

start_position_p out param set to the start position of the specified recording

§Parameters

recording_id the active recording id

source

pub fn get_stop_position(&self, recording_id: i64) -> Result<i64, AeronCError>

Fetch the stop position for the specified recording.

§Return

stop_position_p out param set to the stop position of the specified recording

§Parameters

recording_id the active recording id

source

pub fn get_max_recorded_position( &self, recording_id: i64, ) -> Result<i64, AeronCError>

Fetch the stop or active position for the specified recording.

§Return

max_recorded_position_p out param set to the stop or active position of the specified recording

§Parameters

recording_id the active recording id

source

pub fn stop_recording_subscription( &self, subscription_id: i64, ) -> Result<i32, AeronCError>

Stop recording for the specified subscription id. This is the subscription id returned from aeron_archive_start_recording or aeron_archive_extend_recording.

§Parameters

subscription_id the subscription id for the recording in the Aeron Archive

§Return

0 for success, -1 for failure

source

pub fn try_stop_recording_subscription( &self, subscription_id: i64, ) -> Result<bool, AeronCError>

Try to stop a recording for the specified subscription id. This is the subscription id returned from aeron_archive_start_recording or aeron_archive_extend_recording.

§Return

stopped_p out param indicating true if stopped, or false if the subscription is not currently active

§Parameters

subscription_id the subscription id for the recording in the Aeron Archive

source

pub fn stop_recording_channel_and_stream( &self, channel: &str, stream_id: i32, ) -> Result<i32, AeronCError>

Stop recording for the specified channel and stream.

Channels that include session id parameters are considered different than channels without session ids. Stopping a recording on a channel without a session id parameter will not stop the recording of any session id specific recordings that use the same channel and stream id.

§Parameters

channel the channel of the recording to be stopped
stream_id the stream id of the recording to be stopped

§Return

0 for success, -1 for failure

source

pub fn try_stop_recording_channel_and_stream( &self, channel: &str, stream_id: i32, ) -> Result<bool, AeronCError>

Try to stop recording for the specified channel and stream.

Channels that include session id parameters are considered different than channels without session ids. Stopping a recording on a channel without a session id parameter will not stop the recording of any session id specific recordings that use the same channel and stream id.

§Return

stopped_p out param indicating true if stopped, or false if the channel/stream pair is not currently active

§Parameters

channel the channel of the recording to be stopped
stream_id the stream id of the recording to be stopped

source

pub fn try_stop_recording_by_identity( &self, recording_id: i64, ) -> Result<bool, AeronCError>

Stop recording for the specified recording id.

§Return

stopped_p out param indicating true if stopped, or false if the recording is not currently active

§Parameters

recording_id the id of the recording to be stopped

source

pub fn stop_recording_publication( &self, publication: &AeronPublication, ) -> Result<i32, AeronCError>

Stop recording a session id specific recording that pertains to the given publication.

§Parameters

publication the publication to stop recording

§Return

0 for success, -1 for failure

source

pub fn stop_recording_exclusive_publication( &self, exclusive_publication: &AeronExclusivePublication, ) -> Result<i32, AeronCError>

Stop recording a session id specific recording that pertains to the given exclusive publication.

§Parameters

exclusive_publication the exclusive publication to stop recording

§Return

0 for success, -1 for failure

source

pub fn find_last_matching_recording( &self, min_recording_id: i64, channel_fragment: &str, stream_id: i32, session_id: i32, ) -> Result<i64, AeronCError>

Find the last recording that matches the given criteria.

§Return

recording_id_p out param for the recording id that matches

§Parameters

min_recording_id the lowest recording id to search back to
channel_fragment for a ‘contains’ match on the original channel stored with the Aeron Archive
stream_id the stream id of the recording
session_id the session id of the recording

source

pub fn list_recording<AeronArchiveRecordingDescriptorConsumerFuncHandlerImpl: AeronArchiveRecordingDescriptorConsumerFuncCallback>( &self, recording_id: i64, recording_descriptor_consumer: Option<&Handler<AeronArchiveRecordingDescriptorConsumerFuncHandlerImpl>>, ) -> Result<i32, AeronCError>

List a recording descriptor for a single recording id.

§Return

count_p out param indicating the number of descriptors found

§Parameters

recording_id the id of the recording
recording_descriptor_consumer to be called for each descriptor
recording_descriptor_consumer_clientd to be passed for each descriptor

source

pub fn list_recordings<AeronArchiveRecordingDescriptorConsumerFuncHandlerImpl: AeronArchiveRecordingDescriptorConsumerFuncCallback>( &self, from_recording_id: i64, record_count: i32, recording_descriptor_consumer: Option<&Handler<AeronArchiveRecordingDescriptorConsumerFuncHandlerImpl>>, ) -> Result<i32, AeronCError>

List all recording descriptors starting at a particular recording id, with a limit of total descriptors delivered.

§Return

count_p out param indicating the number of descriptors found

§Parameters

from_recording_id the id at which to begin the listing
record_count the limit of total descriptors to deliver
recording_descriptor_consumer to be called for each descriptor
recording_descriptor_consumer_clientd to be passed for each descriptor

source

pub fn list_recordings_for_uri<AeronArchiveRecordingDescriptorConsumerFuncHandlerImpl: AeronArchiveRecordingDescriptorConsumerFuncCallback>( &self, from_recording_id: i64, record_count: i32, channel_fragment: &str, stream_id: i32, recording_descriptor_consumer: Option<&Handler<AeronArchiveRecordingDescriptorConsumerFuncHandlerImpl>>, ) -> Result<i32, AeronCError>

List all recording descriptors for a given channel fragment and stream id, starting at a particular recording id, with a limit of total descriptors delivered.

§Return

count_p out param indicating the number of descriptors found

§Parameters

from_recording_id the id at which to begin the listing
record_count the limit of total descriptors to deliver
channel_fragment for a ‘contains’ match on the original channel stored with the Aeron Archive
stream_id the stream id of the recording
recording_descriptor_consumer to be called for each descriptor
recording_descriptor_consumer_clientd to be passed for each descriptor

source

pub fn start_replay( &self, recording_id: i64, replay_channel: &str, replay_stream_id: i32, params: &AeronArchiveReplayParams, ) -> Result<i64, AeronCError>

Start a replay

The lower 32-bits of the replay session id contain the session id of the image of the received replay and can be obtained by casting the replay session id to an int32_t. All 64-bits are required to uniquely identify the replay when calling aeron_archive_stop_replay.

§Return

replay_session_id_p out param set to the replay session id

§Parameters

recording_id the id of the recording
replay_channel the channel to which the replay should be sent
replay_stream_id the stream id to which the replay should be sent
params the AeronArchiveReplayParams that control the behaviour of the replay

source

pub fn truncate_recording( &self, recording_id: i64, position: i64, ) -> Result<i64, AeronCError>

Truncate a stopped recording to the specified position. The position must be less than the stopped position. The position must be on a fragment boundary. Truncating a recording to the start position effectively deletes the recording.

§Return

count_p out param set to the number of segments deleted

§Parameters

recording_id the id of the recording
position the position to which the recording will be truncated

source

pub fn stop_replay(&self, replay_session_id: i64) -> Result<i32, AeronCError>

Stop a replay session.

§Parameters

replay_session_id the replay session id indicating the replay to stop

§Return

0 for success, -1 for failure

source

pub fn stop_all_replays(&self, recording_id: i64) -> Result<i32, AeronCError>

Stop all replays matching a recording id. If recording_id is AERON_NULL_VALUE then match all replays.

§Parameters

recording_id the id of the recording for which all replays will be stopped

§Return

0 for success, -1 for failure

source

pub fn list_recording_subscriptions<AeronArchiveRecordingSubscriptionDescriptorConsumerFuncHandlerImpl: AeronArchiveRecordingSubscriptionDescriptorConsumerFuncCallback>( &self, pseudo_index: i32, subscription_count: i32, channel_fragment: &str, stream_id: i32, apply_stream_id: bool, recording_subscription_descriptor_consumer: Option<&Handler<AeronArchiveRecordingSubscriptionDescriptorConsumerFuncHandlerImpl>>, ) -> Result<i32, AeronCError>

List active recording subscriptions in the Aeron Archive. These are the result of calling aeron_archive_start_recording or aeron_archive_extend_recording. The subscription id in the returned descriptor can be used when calling aeron_archive_stop_recording_subscription.

§Return

count_p out param set to the count of matched subscriptions

§Parameters

pseudo_index the index into the active list at which to begin listing
subscription_count the limit of total descriptors to deliver
channel_fragment for a ‘contains’ match on the original channel stored with the Aeron Archive
stream_id the stream id of the recording
apply_stream_id whether or not the stream id should be matched
recording_subscription_descriptor_consumer to be called for each descriptor
recording_subscription_descriptor_consumer_clientd to be passed for each descriptor

source

pub fn purge_recording(&self, recording_id: i64) -> Result<i64, AeronCError>

Purge a stopped recording. i.e. Mark the recording as INVALID at the Archive and delete the corresponding segment files. The space in the Catalog will be reclaimed upon compaction.

§Return

deleted_segments_count_p out param set to the number of deleted segments

§Parameters

recording_id the id of the stopped recording to be purged

source

pub fn extend_recording( &self, recording_id: i64, recording_channel: &str, recording_stream_id: i32, source_location: aeron_archive_source_location_t, auto_stop: bool, ) -> Result<i64, AeronCError>

Extend an existing, non-active recording for a channel and stream pairing.

The channel must be configured with the initial position from which it will be extended. This can be done with aeron_uri_string_builder_set_initial_position. The details required to initialize can be found by calling aeron_archive_list_recording.

§Return

subscription_id_p out param set to the subscription id of the recording

§Parameters

recording_id the id of the existing recording
recording_channel the channel of the publication to be recorded
recording_stream_id the stream id of the publication to be recorded
source_location the source location of the publication to be recorded
auto_stop should the recording be automatically stopped when complete

source

pub fn replicate( &self, src_recording_id: i64, src_control_channel: &str, src_control_stream_id: i32, params: &AeronArchiveReplicationParams, ) -> Result<i64, AeronCError>

Replicate a recording from a source Archive to a destination. This can be considered a backup for a primary Archive. The source recording will be replayed via the provided replay channel and use the original stream id. The behavior of the replication will be governed by the values specified in the AeronArchiveReplicationParams.

For a source recording that is still active, the replay can merge with the live stream and then follow it directly and no longer require the replay from the source. This would require a multicast live destination.

Errors will be reported asynchronously and can be checked for with aeron_archive_check_for_error_response and aeron_archive_poll_for_error_response.

§Return

replication_id_p out param set to the replication id that can be used to stop the replication

§Parameters

src_recording_id the recording id that must exist at the source Archive
src_control_channel remote control channel for the source archive on which to instruct the replay
src_control_stream_id remote control stream id for the source archive on which to instruct the replay
params optional parameters to configure the behavior of the replication

source

pub fn stop_replication(&self, replication_id: i64) -> Result<i32, AeronCError>

Stop a replication by the replication id.

§Parameters

replication_id the replication id retrieved when calling aeron_archive_replicate

§Return

0 for success, -1 for failure

source

pub fn try_stop_replication( &self, replication_id: i64, ) -> Result<bool, AeronCError>

Try to stop a replication by the replication id.

§Return

stopped_p out param indicating true if stopped, or false if the recording is not currently active

§Parameters

replication_id the replication id retrieved when calling aeron_archive_replicate

source

pub fn detach_segments( &self, recording_id: i64, new_start_position: i64, ) -> Result<i32, AeronCError>

Detach segments from the beginning of a recording up to the provided new start position.

The new start position must be the first byte position of a segment after the existing start position.

It is not possible to detach segments which are active for recording or being replayed.

§Parameters

recording_id the id of an existing recording
new_start_position the new starting position for the recording after the segments are detached

§Return

0 for success, -1 for failure

source

pub fn delete_detached_segments( &self, recording_id: i64, ) -> Result<i64, AeronCError>

Delete segments which have been previously detached from a recording.

§Return

count_p out param set to the number of segments deleted

§Parameters

recording_id the id of an existing recording

source

pub fn purge_segments( &self, recording_id: i64, new_start_position: i64, ) -> Result<i64, AeronCError>

Purge (Detach and delete) segments from the beginning of a recording up to the provided new start position.

The new start position must be the first byte position of a segment after the existing start position.

It is not possible to detach segments which are active for recording or being replayed.

§Return

count_p out param set to the number of segments deleted

§Parameters

recording_id the id of an existing recording
new_start_position the new starting position for the recording after the segments are detached

source

pub fn attach_segments(&self, recording_id: i64) -> Result<i64, AeronCError>

Attach segments to the beginning of a recording to restore history that was previously detached.

Segment files must match the existing recording and join exactly to the start position of the recording they are being attached to.

§Return

count_p out param set to the number of segments attached

§Parameters

recording_id the id of an existing recording

source

pub fn migrate_segments( &self, src_recording_id: i64, dst_recording_id: i64, ) -> Result<i64, AeronCError>

Migrate segments from a source recording and attach them to the beginning of a destination recording.

The source recording must match the destination recording for segment length, term length, mtu length, stream id, plus the stop position and term id of the source must join with the start position of the destination and be on a segment boundary.

The source recording will be effectively truncated back to its start position after the migration.

§Return

count_p out param set to the number of segments deleted

§Parameters

src_recording_id the id of an existing recording from which segments will be migrated
dst_recording_id the id of an existing recording to which segments will be migrated

source

pub fn segment_file_base_position( start_position: i64, position: i64, term_buffer_length: i32, segment_file_length: i32, ) -> i64

Position of the recorded stream at the base of a segment file.

If a recording starts within a term then the base position can be before the recording started.

§Parameters

start_position start position of the stream
position position in the stream to calculate the segment base position from.
term_buffer_length term buffer length of the stream
segment_file_length segment file length, which is a multiple of term buffer length