Struct lsl::StreamInlet

pub struct StreamInlet { /* fields omitted */ }

A stream inlet. Inlets are used to receive streaming data (and meta-data) from the lab network.

The actual sample-pulling functionality is provided via the Pullable trait below.

Examples: the receive_*.rs examples (found in the crate's github repository) illustrate the use of StreamInlet.

Errors

For operations where a timeout is provided, if the operation does not complete in time, an Error::Timeout will be returned -- except for the pull_*() functions, where this is not considered an error. Also, for most operations, an Error::StreamLost is returned if the stream source has been lost in the meantime (see also recover option in the inlet's new() constructor).

Implementations

impl StreamInlet

pub fn new(
    info: &StreamInfo,
    max_buflen: i32,
    max_chunklen: i32,
    recover: bool
) -> Result<StreamInlet, Error>

Construct a new stream inlet from a resolved stream info.

Arguments:

• info: A resolved stream info object (as coming from one of the resolver functions). Note: the StreamInlet may also be constructed with a manually-constructed StreamInfo, if the desired channel format and count is already known up-front, but this is strongly discouraged and should only ever be done if there is no time to resolve the stream up-front (e.g., due to limitations in the client program).
• max_buflen: The maximum amount of data to buffer (in seconds if there is a nominal sampling rate, otherwise x100 in samples). Recording applications want to use a fairly large buffer size here (a good default would be 360, which corresponds to 6 minutes of data), while real-time applications would only buffer as much as they need to perform their next calculation (e.g., 1-10).
• max_chunklen: The maximum size, in samples, at which chunks are transmitted (the default corresponds to the chunk sizes used by the sender). If specified as 0, the chunk sizes preferred by the sender are used. Recording applications can use a generous size here (leaving it to the network how to pack things), while real-time applications may want a finer (perhaps 1-sample) granularity.
• recover: Try to silently recover lost streams that are recoverable (those that that have a source_id set). In all other cases (recover is false or the stream is not recoverable) inlet methods may throw a LostError if the stream's source is lost (e.g., due to an app or computer crash).

pub fn info(&self, timeout: f64) -> Result<StreamInfo, Error>

Retrieve the complete information of the given stream, including the extended description. Can be invoked at any time of the stream's lifetime.

Arguments:

• timeout: Timeout of the operation. You can use the value lsl::FOREVER to have no timeout.

pub fn open_stream(&self, timeout: f64) -> Result<(), Error>

Subscribe to the data stream.

All samples pushed in at the other end from this moment onwards will be queued and eventually be delivered in response to pull_sample() or pull_chunk() calls.

In most applications it is not necessary to call this function since the stream will be opened implicitly upon the first call to any of the pull_*() operations. However, it can be used in order to not lose samples that had been sent over the stream prior to the first pull_*() call.

Arguments:

• timeout Optional timeout of the operation. To have no timeout, you can use lsl::FOREVER here. A timeout can make sense if you want to catch connection errors (e.g., due to misconfigured firewalls or the like).

pub fn close_stream(&self)

Unsubscribe from the current data stream.

All samples that are still buffered or in flight will be dropped and transmission and buffering of data for this inlet will be stopped. If an application stops being interested in data from a source (temporarily or not) but keeps the outlet alive, it should call close_stream() to not waste unnecessary system and network resources. This feature is rarely used in practice since it's often simpler to just discard the whole inlet and later recreate it.

pub fn time_correction(&self, timeout: f64) -> Result<f64, Error>

Retrieve an estimated time correction offset for the given stream.

The first call to this function takes several milliseconds until a reliable first estimate is obtained. Subsequent calls are instantaneous (and rely on periodic background updates). On a well-behaved network, the precision of these estimates should be below 1 ms (empirically it is within +/-0.2 ms).

To get a measure of whether the network is well-behaved, see also the extended version time_correction_ex(), which additionally returns the round-trip-time, which is an upper bound for the uncertainty.

Arguments:

• timeout: Timeout to acquire the first time-correction estimate. You can use the value lsl::FOREVER to have no timeout. Otherwise, 2.0-5.0 seconds would be a reasonable timeout. Note that even if the timeout fails, the library will continue to attempt retrieving a time-correction estimate in the background, which can be queried in a subsequent call.

pub fn time_correction_ex(&self, timeout: f64) -> Result<(f64, f64, f64), Error>

Retrieve extended time-correction information for the given stream.

This function is used like time_correction(), but instead returns additional information in a tuple of 3 values, which are (time_offset, remote_time, uncertainty), where:

• time_offset corresponds to the return value of time_correction() (see for explanation).
• remote_time is the remote time when the measurement was made, and consequently remote_time + time_offset is the local time when that measurement was made (this will typically lie as much as a few seconds before the current time point -- not because of inaccuracy, but because measurements are made periodically in the background, and the function only returns the most recent one of them).
• uncertainty is the round-trip-time (RTT) of the measurement in seconds, which is a hard upper bound on the uncertainty of the time offset. Empirically, 0.2 ms a typical RTT for wired networks, 2 ms is typical of wireless networks, but it can be much higher on poor networks.

pub fn set_postprocessing(
    &self,
    options: &[ProcessingOption]
) -> Result<(), Error>

Set post-processing flags to use.

By default, the inlet performs NO post-processing and returns the ground-truth time stamps, which can then be manually synchronized using time_correction(), and then smoothed/dejittered if desired. This function allows automating these two and possibly more operations.

Warning: when you enable this, you will no longer receive or be able to recover the original time stamps.

Arguments:

• options: an array of ProcessingOption values that shall be set. You can also pass in the value [ProcessingOption::ALL] to enable all options or an empty array to clear all previously set options.

pub fn samples_available(&self) -> u32

Query whether samples are currently available for immediate pickup.

Note that it is not a good idea to use samples_available() to determine whether a pull_*() call would block: to be sure, set the pull timeout to 0.0 or an acceptably low value. If the underlying implementation supports it, the value will be the number of samples available (otherwise it will be 1 or 0).

pub fn was_clock_reset(&self) -> bool

Query whether the clock was potentially reset since the last call to was_clock_reset().

This is a rarely-used function that is only useful to applications that combine multiple time_correction values to estimate precise clock drift; it allows to tolerate cases where the machine from which the stream is coming was hot-swapped or restarted in between two measurements.

pub fn smoothing_halftime(&self, value: f32)

Override the half-time (forget factor) of the time-stamp smoothing.

The default is 90 seconds unless a different value is set in the config file. Using a longer window will yield lower jitter in the time stamps, but longer windows will have trouble tracking changes in the clock rate (usually due to temperature changes); the default is able to track changes up to 10 degrees C per minute sufficiently well.

Trait Implementations

impl Debug for StreamInlet

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

Formats the value using the given formatter.

impl Drop for StreamInlet

fn drop(&mut self)

Executes the destructor for this type.

impl Pullable<String> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<String>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<String>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<Vec<u8>> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<Vec<u8>>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<Vec<u8>>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<f32> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<f32>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<f32>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<f64> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<f64>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<f64>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<i16> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<i16>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<i16>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<i32> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<i32>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<i32>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<i64> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<i64>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(
    &self,
    buf: &mut Vec<i64>,
    timeout: f64
) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.

impl Pullable<i8> for StreamInlet

fn pull_sample(&self, timeout: f64) -> Result<(Vec<i8>, f64), Error>

Pull the next successive sample from an inlet and read it into a vector of values.

fn pull_sample_buf(&self, buf: &mut Vec<i8>, timeout: f64) -> Result<f64, Error>

Pull the next successive sample from an inlet into a provided buffer.

fn pull_chunk(&self) -> Result<(Vec<Vec<T>>, Vec<f64>), Error>

Pull a chunk of new samples and their time stamps from the inlet.