pub struct PulsarClient<E: Engine = TokioEngine> { /* private fields */ }Expand description
High-level Pulsar client, generic over the runtime Engine.
Defaults to crate::TokioEngine (the production engine) so existing
callers write PulsarClient::builder() without naming a type parameter.
Callers exercising the moonpool deterministic-simulation engine
parametrise with PulsarClient::<MoonpoolEngine<P>> (see
ADR-0019
gate (e), “Option A”).
Every façade surface (producer, consumer, reader, typed_producer,
typed_consumer, partitioned / multi-topics / pattern / table-view
constructors, transactions, interceptor SPI, …) is implemented only on
PulsarClient<TokioEngine>. Moonpool-side callers that reach
for one of these get a clean trait-bound failure — matching ADR-0019
§Decision “no silent fallbacks”.
Implementations§
Source§impl PulsarClient<TokioEngine>
impl PulsarClient<TokioEngine>
Sourcepub fn builder() -> ClientBuilder
pub fn builder() -> ClientBuilder
Start building a client. Returns a tokio-engine
crate::ClientBuilder — the default E = TokioEngine on
PulsarClient<E>. Users targeting the moonpool engine open
the engine directly via
[magnetar_runtime_moonpool::MoonpoolEngine] (see
PulsarClient::<MoonpoolEngine<P>>::from_moonpool
for the equivalent constructor).
Sourcepub fn memory_limit(&self) -> Option<MemoryLimit>
pub fn memory_limit(&self) -> Option<MemoryLimit>
The global publish memory budget configured at build time, if any.
Mirrors Java PulsarClient#getMemoryLimit. None means no limit was
configured (the Java default).
Note: today this is configuration-only — the runtime does not yet
enforce the limit. See crate::ClientBuilder::memory_limit for the planned
follow-up.
Sourcepub fn poll_replicated_subscription_marker(
&self,
) -> Option<ObservedReplicatedSubscriptionMarker>
pub fn poll_replicated_subscription_marker( &self, ) -> Option<ObservedReplicatedSubscriptionMarker>
PIP-33 (ADR-0034): non-blocking peek for the next replicated-subscription
marker observation buffered by the driver. None when the buffer is empty.
Mirrors magnetar_runtime_tokio::Client::poll_replicated_subscription_marker.
Sourcepub async fn next_replicated_subscription_marker(
&self,
) -> Option<ObservedReplicatedSubscriptionMarker>
pub async fn next_replicated_subscription_marker( &self, ) -> Option<ObservedReplicatedSubscriptionMarker>
PIP-33 (ADR-0034): await the next replicated-subscription marker
observation. Resolves to None when the connection has closed and no
further markers will arrive. Mirrors
magnetar_runtime_tokio::Client::next_replicated_subscription_marker.
Sourcepub async fn shutdown(self)
pub async fn shutdown(self)
Alias for Self::close. Mirrors Java PulsarClient#shutdown, which is just the
blocking form of close — same semantics from Rust because every async future is
already non-blocking from the caller’s perspective.
Sourcepub fn is_connected(&self) -> bool
pub fn is_connected(&self) -> bool
Returns true while the underlying broker connection is up. Mirrors Java’s
org.apache.pulsar.client.api.Producer#isConnected and
Consumer#isConnected at the client scope.
Sourcepub fn is_closed(&self) -> bool
pub fn is_closed(&self) -> bool
true once Self::close has been called or the broker connection has entered a
terminal state. Mirrors Java PulsarClient#isClosed.
Sourcepub fn last_disconnected_timestamp(&self) -> Option<SystemTime>
pub fn last_disconnected_timestamp(&self) -> Option<SystemTime>
Wall-clock time the underlying broker connection was most recently torn down (peer
EOF, I/O error, or an explicit close()). None while it has never been torn down.
Mirrors org.apache.pulsar.client.api.Producer#getLastDisconnectedTimestamp /
Consumer#getLastDisconnectedTimestamp. Convert with
std::time::SystemTime::duration_since for Java-style millis-since-epoch.
Source§impl<E: Engine> PulsarClient<E>
impl<E: Engine> PulsarClient<E>
Sourcepub fn producer(&self, topic: impl Into<String>) -> ProducerBuilder<'_, E>
pub fn producer(&self, topic: impl Into<String>) -> ProducerBuilder<'_, E>
Open a crate::ProducerBuilder for the given topic.
Engine-generic — the underlying transport is selected at
construction time.
Sourcepub fn consumer(&self, topic: impl Into<String>) -> ConsumerBuilder<'_, E>
pub fn consumer(&self, topic: impl Into<String>) -> ConsumerBuilder<'_, E>
Open a crate::ConsumerBuilder for the given topic.
Engine-generic — the underlying transport is selected at
construction time.
Sourcepub fn reader(&self, topic: impl Into<String>) -> ReaderBuilder<'_, E>
pub fn reader(&self, topic: impl Into<String>) -> ReaderBuilder<'_, E>
Open a crate::ReaderBuilder for the given topic. A reader is a
non-durable, exclusive consumer with an auto-generated
subscription — useful for log inspection and replay.
Engine-generic — the underlying transport is selected at
construction time.
Sourcepub fn typed_producer<S: Schema>(
&self,
topic: impl Into<String>,
schema: Arc<S>,
) -> TypedProducerBuilder<'_, S, E>
pub fn typed_producer<S: Schema>( &self, topic: impl Into<String>, schema: Arc<S>, ) -> TypedProducerBuilder<'_, S, E>
Open a schema-aware crate::TypedProducerBuilder for the given topic. Mirrors Java’s
PulsarClient#newProducer(Schema<T>). Engine-generic per ADR-0026 §D1.
Sourcepub fn typed_consumer<S: Schema>(
&self,
topic: impl Into<String>,
schema: Arc<S>,
) -> TypedConsumerBuilder<'_, S, E>
pub fn typed_consumer<S: Schema>( &self, topic: impl Into<String>, schema: Arc<S>, ) -> TypedConsumerBuilder<'_, S, E>
Open a schema-aware crate::TypedConsumerBuilder for the given topic. Mirrors Java’s
PulsarClient#newConsumer(Schema<T>). Engine-generic per ADR-0026 §D1.
Sourcepub fn multi_topics_consumer(&self) -> MultiTopicsConsumerBuilder<'_, E>
pub fn multi_topics_consumer(&self) -> MultiTopicsConsumerBuilder<'_, E>
Open a crate::MultiTopicsConsumerBuilder that subscribes to many topics at once.
Mirrors Java’s PulsarClient#newConsumer().topics(...). Engine-generic per
ADR-0026 §D1 — .subscribe() routes through the engine-generic
crate::ConsumerBuilder.
Sourcepub fn pattern_consumer(&self) -> PatternConsumerBuilder<'_, E>
pub fn pattern_consumer(&self) -> PatternConsumerBuilder<'_, E>
Open a crate::PatternConsumerBuilder that subscribes to every topic in a namespace
matching a broker-side regex pattern (PIP-145). Reconciles against TopicListChanged
deltas on demand via crate::PatternConsumer::update. Mirrors Java’s
PulsarClient#newConsumer().topicsPattern(...). Engine-generic per ADR-0026 §D1.
Sourcepub fn partitioned_consumer(
&self,
topic: impl Into<String>,
) -> PartitionedConsumerBuilder<'_, E>
pub fn partitioned_consumer( &self, topic: impl Into<String>, ) -> PartitionedConsumerBuilder<'_, E>
Open a crate::PartitionedConsumerBuilder for the given topic. The builder
auto-discovers the partition count and subscribes to every partition under a single
subscription name. Mirrors Java’s PulsarClient#newConsumer() against a partitioned
topic. Engine-generic per ADR-0026 §D1.
Sourcepub fn partitioned_producer(
&self,
topic: impl Into<String>,
) -> PartitionedProducerBuilder<'_, E>
pub fn partitioned_producer( &self, topic: impl Into<String>, ) -> PartitionedProducerBuilder<'_, E>
Open a crate::PartitionedProducerBuilder for the given topic.
The builder queries the broker for the partition count and opens
one child producer per partition. Mirrors Java’s
PulsarClient#newProducer() against a partitioned topic.
Engine-generic — both runtimes’
Client types implement crate::BrokerMetadataApi +
crate::CreateProducerApi so the same builder shape works
against tokio or moonpool.
Sourcepub fn table_view(&self, topic: impl Into<String>) -> TableViewBuilder<'_, E>
pub fn table_view(&self, topic: impl Into<String>) -> TableViewBuilder<'_, E>
Open a crate::TableViewBuilder for the given topic. A
crate::TableView is a key/value snapshot built from a
compacted topic — useful for config snapshots and similar
“latest value wins per key” patterns. Mirrors
PulsarClient#newTableViewBuilder. Engine-generic — dispatches
through crate::SubscribeApi under the hood.
Sourcepub fn typed_table_view<S: Schema>(
&self,
topic: impl Into<String>,
schema: Arc<S>,
) -> TypedTableViewBuilder<'_, S, E>
pub fn typed_table_view<S: Schema>( &self, topic: impl Into<String>, schema: Arc<S>, ) -> TypedTableViewBuilder<'_, S, E>
Schema-aware crate::TypedTableView builder. Mirrors Java
pulsar.tableViewBuilder(Schema) — the view decodes payloads on
read so getters return S::Owned directly. Engine-generic.
Source§impl<E: Engine> PulsarClient<E>where
E::ClientState: BrokerMetadataApi,
Broker-metadata methods that dispatch through the
crate::BrokerMetadataApi extension trait. Engine-generic per
ADR-0026 §D1 — both runtimes implement BrokerMetadataApi on their
Client type.
impl<E: Engine> PulsarClient<E>where
E::ClientState: BrokerMetadataApi,
Broker-metadata methods that dispatch through the
crate::BrokerMetadataApi extension trait. Engine-generic per
ADR-0026 §D1 — both runtimes implement BrokerMetadataApi on their
Client type.
Sourcepub async fn partitions_for_topic(
&self,
topic: &str,
) -> Result<u32, PulsarError>
pub async fn partitions_for_topic( &self, topic: &str, ) -> Result<u32, PulsarError>
Query the broker for the partition count of topic. Returns 0 for non-partitioned
topics. Mirrors Java PulsarClient#getPartitionsForTopic.
§Errors
Returns PulsarError::Other if the broker refuses the metadata lookup.
Sourcepub async fn topic_list_snapshot(
&self,
namespace: &str,
pattern: &str,
) -> Result<Vec<String>, PulsarError>
pub async fn topic_list_snapshot( &self, namespace: &str, pattern: &str, ) -> Result<Vec<String>, PulsarError>
Subscribe to a topic-list watcher and return the initial topic snapshot for the
given namespace + regex pattern (PIP-145). Useful for “discover all topics matching
this pattern right now” workflows. Live updates are emitted by the connection as
TopicListChanged events and surfaced through
crate::BrokerMetadataApi::poll_topic_list_change.
§Errors
Returns PulsarError::Other if the broker refuses the watch.
Source§impl<E: Engine> PulsarClient<E>where
E::ClientState: TransactionApi,
impl<E: Engine> PulsarClient<E>where
E::ClientState: TransactionApi,
Sourcepub async fn new_transaction(
&self,
timeout: Duration,
) -> Result<Transaction, PulsarError>
pub async fn new_transaction( &self, timeout: Duration, ) -> Result<Transaction, PulsarError>
Open a new Pulsar transaction at the broker-side transaction coordinator (PIP-31).
Mirrors Java PulsarClient#newTransaction().
§Errors
PulsarError::Other(with the runtime’s error stringified) on broker rejection or wire failure.
Sourcepub async fn register_partition_to_transaction(
&self,
txn: Transaction,
topic: impl Into<String>,
) -> Result<(), PulsarError>
pub async fn register_partition_to_transaction( &self, txn: Transaction, topic: impl Into<String>, ) -> Result<(), PulsarError>
Register a partition that the given transaction will write to.
Mirrors Java Transaction#registerProducedTopic.
§Errors
PulsarError::Otheron broker rejection or wire failure.
Sourcepub async fn register_subscription_to_transaction(
&self,
txn: Transaction,
topic: impl Into<String>,
subscription: impl Into<String>,
) -> Result<(), PulsarError>
pub async fn register_subscription_to_transaction( &self, txn: Transaction, topic: impl Into<String>, subscription: impl Into<String>, ) -> Result<(), PulsarError>
Register a subscription that the given transaction will acknowledge on.
Mirrors Java Transaction#registerSubscriptionToTxn.
§Errors
PulsarError::Otheron broker rejection or wire failure.
Sourcepub async fn commit_transaction(
&self,
txn: Transaction,
) -> Result<TxnState, PulsarError>
pub async fn commit_transaction( &self, txn: Transaction, ) -> Result<TxnState, PulsarError>
Commit a transaction at the TC. Returns the final state reported by the TC.
Mirrors Java Transaction#commit.
§Errors
PulsarError::Otheron broker rejection or wire failure.
Sourcepub async fn abort_transaction(
&self,
txn: Transaction,
) -> Result<TxnState, PulsarError>
pub async fn abort_transaction( &self, txn: Transaction, ) -> Result<TxnState, PulsarError>
Abort a transaction at the TC. Returns the final state reported by the TC. Mirrors
Java Transaction#abort.
§Errors
PulsarError::Otheron broker rejection or wire failure.