Struct Subscription 

pub struct Subscription { /* private fields */ }

A request to subscribe to a set of items.

Build one, hand it to Client::subscribe, and consume the Updates stream you get back. The three values with no default — the mode, the items and the fields — are taken by Subscription::new; everything else is optional and defaults to letting the server decide.

Not every combination is a subscription

The optional parameters are not independent of the mode: a snapshot length is admitted only in SubscriptionMode::Distinct, and a snapshot, a frequency cap and a buffer size are each meaningless in SubscriptionMode::Raw [docs/spec/03-requests.md §6.1]. The setters stay infallible so that they chain, and the whole combination is checked at once by Subscription::validate — which Client::subscribe calls before anything is sent, so an impossible subscription is a typed error at the call rather than a stream that never activates.

Examples

use lightstreamer_rs::{FieldSchema, ItemGroup, Snapshot, Subscription, SubscriptionMode};

let subscription = Subscription::new(
    SubscriptionMode::Merge,
    ItemGroup::from_items(["item1", "item2"])?,
    FieldSchema::from_fields(["last_price", "time"])?,
)
.with_snapshot(Snapshot::On);

assert_eq!(subscription.mode(), SubscriptionMode::Merge);

Implementations

impl Subscription

pub fn new( mode: SubscriptionMode, items: ItemGroup, fields: FieldSchema, ) -> Self

A subscription to a set of items, for a set of fields, in a mode.

pub fn with_data_adapter(self, name: impl Into<String>) -> Self

Names the Data Adapter within the session’s Adapter Set that provides these items.

Left unset, the server uses the Adapter Set’s default Data Adapter [docs/spec/03-requests.md §6.1].

pub fn with_selector(self, name: impl Into<String>) -> Self

Passes a selector name to the Metadata Adapter, which uses it to filter the updates of every item in the subscription [docs/spec/03-requests.md §6.1].

What a selector name means is entirely up to the adapter.

pub const fn with_snapshot(self, snapshot: Snapshot) -> Self

Asks for a snapshot before the live flow.

pub fn with_max_frequency(self, frequency: MaxFrequency) -> Self

Caps how often the server sends updates for each item.

pub const fn with_buffer_size(self, size: BufferSize) -> Self

Asks the server for a particular per-item buffer size.

pub const fn mode(&self) -> SubscriptionMode

The mode this subscription was built with.

pub const fn items(&self) -> &ItemGroup

The items this subscription covers.

pub const fn fields(&self) -> &FieldSchema

The fields this subscription asks for.

pub const fn snapshot(&self) -> Snapshot

Whether a snapshot was asked for.

pub fn validate(&self) -> Result<(), ConfigError>

Checks that the mode admits every option this subscription carries.

Client::subscribe calls this first, so a caller never has to; it is public because checking a configuration before a client exists is sometimes what you want, and because the error is more useful at the line that built the subscription than at the line that sent it.

Errors

• ConfigError::SnapshotLengthNeedsDistinct — a Snapshot::Length outside SubscriptionMode::Distinct. This one is the specification’s own rule: a length is “admitted only if LS_mode is DISTINCT” [docs/spec/03-requests.md §6.1].
• ConfigError::SnapshotNeedsAStatefulMode — a snapshot in SubscriptionMode::Raw, which keeps no state to snapshot.
• ConfigError::FrequencyNeedsAFilteredMode — a frequency cap in SubscriptionMode::Raw, which the server does not filter.
• ConfigError::BufferSizeNeedsMergeOrDistinct — a buffer size outside SubscriptionMode::Merge and SubscriptionMode::Distinct.
• ConfigError::BufferSizeWithUnfilteredFrequency — a buffer size alongside MaxFrequency::Unfiltered, which the server ignores.

The last four are refused rather than dropped. The server would accept the request and ignore the parameter [docs/spec/03-requests.md §6.1], which means a caller who asked for a cap would run without one and never be told — a silent difference between what was written and what is happening.

Examples

use lightstreamer_rs::{
    ConfigError, FieldSchema, ItemGroup, Snapshot, Subscription, SubscriptionMode,
};

let raw = Subscription::new(
    SubscriptionMode::Raw,
    ItemGroup::from_items(["item1"])?,
    FieldSchema::from_fields(["last_price"])?,
)
.with_snapshot(Snapshot::On);

assert!(matches!(
    raw.validate(),
    Err(ConfigError::SnapshotNeedsAStatefulMode)
));

Trait Implementations

impl Clone for Subscription

fn clone(&self) -> Subscription

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Subscription

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Subscription

impl PartialEq for Subscription

fn eq(&self, other: &Subscription) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Subscription