Struct AeronSubscription

Source

pub struct AeronSubscription { /* private fields */ }

Implementations§

Source §

impl AeronSubscription

Source

pub fn new_zeroed_on_heap() -> Self

creates zeroed struct where the underlying c struct is on the heap

Source

pub fn new_zeroed_on_stack() -> Self

creates zeroed struct where the underlying c struct is on the stack (Use with care)

Source

pub fn poll<AeronFragmentHandlerHandlerImpl: AeronFragmentHandlerCallback>( &self, handler: Option<&Handler<AeronFragmentHandlerHandlerImpl>>, fragment_limit: usize, ) -> Result<i32, AeronCError>

Poll the images under the subscription for available message fragments.

Each fragment read will be a whole message if it is under MTU length. If larger than MTU then it will come as a series of fragments ordered within a session.

To assemble messages that span multiple fragments then use AeronFragmentAssembler.

§Parameters

handler for handling each message fragment as it is read.
fragment_limit number of message fragments to limit when polling across multiple images.

§Return

the number of fragments received or -1 for error.

Source

pub fn poll_fn<AeronFragmentHandlerHandlerImpl: FnMut(&[u8], AeronHeader)>( &self, handler: AeronFragmentHandlerHandlerImpl, fragment_limit: usize, ) -> Result<i32, AeronCError>

Poll the images under the subscription for available message fragments.

Each fragment read will be a whole message if it is under MTU length. If larger than MTU then it will come as a series of fragments ordered within a session.

To assemble messages that span multiple fragments then use AeronFragmentAssembler.

§Parameters

handler for handling each message fragment as it is read.
fragment_limit number of message fragments to limit when polling across multiple images.

§Return

the number of fragments received or -1 for error.

Stack-borrowed closure (_fn variant): the FnMut closure lives on the caller’s stack and is borrowed for this call only — the callback fires synchronously inside the call, so nothing is heap-allocated, nothing is stored, and the closure may borrow local state. Prefer this over the retained Handler-based form on the hot path; only generated for callbacks the C client does not retain (i.e. not stored for later firing).

§Panics

A panic inside the closure cannot unwind across the extern "C" callback boundary and aborts the process (since Rust 1.81). Return early instead of panicking in production fragment handlers.

Source

pub fn controlled_poll<AeronControlledFragmentHandlerHandlerImpl: AeronControlledFragmentHandlerCallback>( &self, handler: Option<&Handler<AeronControlledFragmentHandlerHandlerImpl>>, fragment_limit: usize, ) -> Result<i32, AeronCError>

Poll in a controlled manner the images under the subscription for available message fragments. Control is applied to fragments in the stream. If more fragments can be read on another stream they will even if BREAK or ABORT is returned from the fragment handler.

Each fragment read will be a whole message if it is under MTU length. If larger than MTU then it will come as a series of fragments ordered within a session.

To assemble messages that span multiple fragments then use AeronControlledFragmentAssembler.

§Parameters

handler for handling each message fragment as it is read.
fragment_limit number of message fragments to limit when polling across multiple images.

§Return

the number of fragments received or -1 for error.

Source

pub fn controlled_poll_fn<AeronControlledFragmentHandlerHandlerImpl: FnMut(&[u8], AeronHeader) -> aeron_controlled_fragment_handler_action_t>( &self, handler: AeronControlledFragmentHandlerHandlerImpl, fragment_limit: usize, ) -> Result<i32, AeronCError>

Poll in a controlled manner the images under the subscription for available message fragments. Control is applied to fragments in the stream. If more fragments can be read on another stream they will even if BREAK or ABORT is returned from the fragment handler.

Each fragment read will be a whole message if it is under MTU length. If larger than MTU then it will come as a series of fragments ordered within a session.

To assemble messages that span multiple fragments then use AeronControlledFragmentAssembler.

§Parameters

handler for handling each message fragment as it is read.
fragment_limit number of message fragments to limit when polling across multiple images.

§Return

the number of fragments received or -1 for error.

Stack-borrowed closure (_fn variant): the FnMut closure lives on the caller’s stack and is borrowed for this call only — the callback fires synchronously inside the call, so nothing is heap-allocated, nothing is stored, and the closure may borrow local state. Prefer this over the retained Handler-based form on the hot path; only generated for callbacks the C client does not retain (i.e. not stored for later firing).

§Panics

A panic inside the closure cannot unwind across the extern "C" callback boundary and aborts the process (since Rust 1.81). Return early instead of panicking in production fragment handlers.

Source

pub fn block_poll<AeronBlockHandlerHandlerImpl: AeronBlockHandlerCallback>( &self, handler: Option<&Handler<AeronBlockHandlerHandlerImpl>>, block_length_limit: usize, ) -> c_long

Poll the images under the subscription for available message fragments in blocks.

This method is useful for operations like bulk archiving and messaging indexing.

§Parameters

handler to receive a block of fragments from each image.
block_length_limit for each image polled.

§Return

the number of bytes consumed or -1 for error.

Source

pub fn block_poll_fn<AeronBlockHandlerHandlerImpl: FnMut(&[u8], i32, i32)>( &self, handler: AeronBlockHandlerHandlerImpl, block_length_limit: usize, ) -> c_long

Poll the images under the subscription for available message fragments in blocks.

This method is useful for operations like bulk archiving and messaging indexing.

§Parameters

handler to receive a block of fragments from each image.
block_length_limit for each image polled.

§Return

the number of bytes consumed or -1 for error.

Stack-borrowed closure (_fn variant): the FnMut closure lives on the caller’s stack and is borrowed for this call only — the callback fires synchronously inside the call, so nothing is heap-allocated, nothing is stored, and the closure may borrow local state. Prefer this over the retained Handler-based form on the hot path; only generated for callbacks the C client does not retain (i.e. not stored for later firing).

§Panics

A panic inside the closure cannot unwind across the extern "C" callback boundary and aborts the process (since Rust 1.81). Return early instead of panicking in production fragment handlers.

Source

pub fn is_connected(&self) -> bool

Is this subscription connected by having at least one open publication image.

§Return

true if this subscription connected by having at least one open publication image.

Source

pub fn constants( &self, constants: &AeronSubscriptionConstants, ) -> Result<i32, AeronCError>

Fill in a structure with the constants in use by a subscription.

§Parameters

subscription to get the constants for.
constants structure to fill in with the constants

§Return

0 for success and -1 for error.

Source

pub fn get_constants(&self) -> Result<AeronSubscriptionConstants, AeronCError>

Fill in a structure with the constants in use by a subscription.

Source

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

Count of images associated to this subscription.

§Return

count of count associated to this subscription or -1 for error.

Source

pub fn image_retain(&self, image: &AeronImage) -> Result<i32, AeronCError>

Retain the given image for access in the application.

Note: A retain call must have a corresponding release call. Note: Subscriptions are not threadsafe and should not be shared between subscribers.

§Parameters

subscription that image is part of.
image to retain

§Return

0 for success and -1 for error.

Source

pub fn image_release(&self, image: &AeronImage) -> Result<i32, AeronCError>

Release the given image and relinquish desire to use the image directly.

Note: Subscriptions are not threadsafe and should not be shared between subscribers.

§Parameters

subscription that image is part of.
image to release

§Return

0 for success and -1 for error.

Source

pub fn is_closed(&self) -> bool

Is the subscription closed.

§Return

true if it has been closed otherwise false.

Source

pub fn channel_status(&self) -> i64

Get the status of the media channel for this subscription.

The status will be ERRORED (-1) if a socket exception occurs on setup and ACTIVE (1) if all is well.

§Return

1 for ACTIVE, -1 for ERRORED

Source

pub fn local_sockaddrs( &self, address_vec: &AeronIovec, address_vec_len: usize, ) -> Result<i32, AeronCError>

Get all of the local socket addresses for this subscription. Multiple addresses can occur if this is a multi-destination subscription. Addresses will a string representation in numeric form. IPv6 addresses will be surrounded by ‘[’ and ‘]’ so that the ‘:’ that separate the parts are distinguishable from the port delimiter. E.g. [fe80::7552:c06e:6bf4:4160]:12345. As of writing the maximum length for a formatted address is 54 bytes including the NULL terminator. AERON_CLIENT_MAX_LOCAL_ADDRESS_STR_LEN is defined to provide enough space to fit the returned string. Returned strings will be NULL terminated. If the buffer to hold the address can not hold enough of the message it will be truncated and the last character will be null.

If the address_vec_len is less the total number of addresses available then the first addresses found up to that length will be placed into the address_vec. However the function will return the total number of addresses available so if if that is larger than the input array then the client code may wish to re-query with a larger array to get them all.

§Parameters

address_vec to hold the received addresses
address_vec_len available length of the vector to hold the addresses

§Return

number of addresses found or -1 if there is an error.

Source

pub fn resolved_endpoint(&self, address: &str) -> Result<i32, AeronCError>

Retrieves the first local socket address for this subscription. If this is not MDS then it will be the one representing endpoint for this subscription.

@see aeron_subscription_local_sockaddrs

§Parameters

address for the received address
address_len available length for the copied address.

§Return

-1 on error, 0 if address not found, 1 if address is found.

Source

pub fn try_resolve_channel_endpoint_port( &self, uri: &mut [u8], ) -> Result<i32, AeronCError>

Retrieves the channel URI for this subscription with any wildcard ports filled in. If the channel is not UDP or does not have a wildcard port (0), then it will return the original URI.

§Parameters

uri buffer to hold the resolved uri
uri_len length of the buffer

§Return

-1 on failure or the number of bytes written to the buffer (excluding the NULL terminator). Writing is done on a per key basis, so if the buffer was truncated before writing completed, it will only include the byte count up to the key that overflowed. However, the invariant that if the number returned >= uri_len, then output will have been truncated.

Source

pub fn try_resolve_channel_endpoint_port_as_string( &self, max_length: usize, ) -> Result<String, AeronCError>

Retrieves the channel URI for this subscription with any wildcard ports filled in. If the channel is not UDP or does not have a wildcard port (0), then it will return the original URI.

§Parameters

uri buffer to hold the resolved uri
uri_len length of the buffer

§Return

-1 on failure or the number of bytes written to the buffer (excluding the NULL terminator). Writing is done on a per key basis, so if the buffer was truncated before writing completed, it will only include the byte count up to the key that overflowed. However, the invariant that if the number returned >= uri_len, then output will have been truncated.

Source

pub fn try_resolve_channel_endpoint_port_into( &self, dst_truncate_to_capacity: &mut String, ) -> Result<i32, AeronCError>

Retrieves the channel URI for this subscription with any wildcard ports filled in. If the channel is not UDP or does not have a wildcard port (0), then it will return the original URI.

§Parameters

uri buffer to hold the resolved uri
uri_len length of the buffer

§Return

-1 on failure or the number of bytes written to the buffer (excluding the NULL terminator). Writing is done on a per key basis, so if the buffer was truncated before writing completed, it will only include the byte count up to the key that overflowed. However, the invariant that if the number returned >= uri_len, then output will have been truncated. NOTE: allocation friendly method, the string capacity must be set as it will truncate string to capacity it will never grow the string. So if you pass String::new() it will write 0 chars

Source

pub fn get_inner(&self) -> *mut aeron_subscription_t

Source

pub unsafe fn get_inner_mut(&self) -> &mut aeron_subscription_t

Mutable access to the underlying C struct, minted from &self: nothing prevents two live &mut at once, so the caller must ensure exclusive access for the lifetime of the returned reference.

§Safety

No other reference (& or &mut) to the underlying struct may be alive while the returned &mut is in use.

Source

pub fn get_inner_ref(&self) -> &aeron_subscription_t

Source §

impl AeronSubscription

Source

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

Closes this resource in the C client immediately; all clones of this handle become closed (their pointer is nulled) and must not be used.

Source §

impl AeronSubscription

Source

pub fn close_with_handler<AeronNotificationHandlerImpl: AeronNotificationCallback>( self, on_close_complete: Option<&Handler<AeronNotificationHandlerImpl>>, ) -> Result<(), AeronCError>

Like Self::close, but notifies on_close_complete when the close finishes. The handler must outlive the notification (keep your Handler alive until it has fired).

Source §

impl AeronSubscription

Source

pub fn image_at_index(&self, index: usize) -> Option<AeronImage>

A retained image handle for index, or None when no such image exists.

The C client retains the image on this call; the returned AeronImage releases it automatically when the last clone drops (no manual aeron_image_release). If the subscription is closed first, the release is skipped — the C client has already reclaimed the image.

Source

pub fn image_by_session_id(&self, session_id: i32) -> Option<AeronImage>

A retained image handle for session_id, or None when no such image exists. Same automatic-release semantics as Self::image_at_index.

Source

pub fn for_each_image<F: FnMut(&AeronImage)>(&self, f: F)

Borrow-scoped iteration over the current images — zero retain/release bookkeeping. The borrowed AeronImage is only valid inside the closure; call Self::image_at_index / Self::image_by_session_id for a handle that outlives it.

Source

pub fn async_add_destination( &self, client: &Aeron, destination: &CStr, ) -> Result<AeronAsyncDestination, AeronCError>

Source

pub fn add_destination( &self, destination: &CStr, timeout: Duration, ) -> Result<(), AeronCError>

Add destination, polling until the driver acknowledges or timeout elapses. The owning Aeron client is retrieved automatically from the subscription’s dependency graph — pass it explicitly via Self::async_add_destination only when you hold it already.

Source §

impl AeronSubscription

Source

pub fn status(&self) -> AeronStatus

High-level connection state derived from the subscription handle.

Source

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

Convenience accessor for the stream id (no direct C accessor exists for subscriptions; backed by Self::get_constants). For a hot loop, call Self::get_constants once and reuse the returned AeronSubscriptionConstants.

Source