Struct rerun::sdk::RecordingStream

pub struct RecordingStream {
    inner: Either<Arc<Option<RecordingStreamInner>>, Weak<Option<RecordingStreamInner>>>,
}

A RecordingStream handles everything related to logging data into Rerun.

You can construct a new RecordingStream using RecordingStreamBuilder or RecordingStream::new.

Sinks

Data is logged into Rerun via LogSinks.

The underlying LogSink of a RecordingStream can be changed at any point during its lifetime by calling RecordingStream::set_sink or one of the higher level helpers (RecordingStream::connect, RecordingStream::memory, RecordingStream::save, RecordingStream::disconnect).

See RecordingStream::set_sink for more information.

Multithreading and ordering

RecordingStream can be cheaply cloned and used freely across any number of threads.

Internally, all operations are linearized into a pipeline:

• All operations sent by a given thread will take effect in the same exact order as that thread originally sent them in, from its point of view.
• There isn’t any well defined global order across multiple threads.

This means that e.g. flushing the pipeline (Self::flush_blocking) guarantees that all previous data sent by the calling thread has been recorded; no more, no less. (e.g. it does not mean that all file caches are flushed)

Shutdown

The RecordingStream can only be shutdown by dropping all instances of it, at which point it will automatically take care of flushing any pending data that might remain in the pipeline.

Shutting down cannot ever block.

Fields

inner: Either<Arc<Option<RecordingStreamInner>>, Weak<Option<RecordingStreamInner>>>

Implementations

impl RecordingStream

pub fn get( kind: StoreKind, overrides: Option<RecordingStream> ) -> Option<RecordingStream>

Returns overrides if it exists, otherwise returns the most appropriate active recording of the specified type (i.e. thread-local first, then global scope), if any.

pub fn global(kind: StoreKind) -> Option<RecordingStream>

Returns the currently active recording of the specified type in the global scope, if any.

pub fn set_global( kind: StoreKind, rec: Option<RecordingStream> ) -> Option<RecordingStream>

Replaces the currently active recording of the specified type in the global scope with the specified one.

Returns the previous one, if any.

pub fn forget_global(kind: StoreKind)

Forgets the currently active recording of the specified type in the global scope.

WARNING: this intentionally bypasses any drop/flush logic. This should only ever be used in cases where you know the batcher/sink threads have been lost such as in a forked process.

pub fn thread_local(kind: StoreKind) -> Option<RecordingStream>

Returns the currently active recording of the specified type in the thread-local scope, if any.

pub fn set_thread_local( kind: StoreKind, rec: Option<RecordingStream> ) -> Option<RecordingStream>

Replaces the currently active recording of the specified type in the thread-local scope with the specified one.

pub fn forget_thread_local(kind: StoreKind)

Forgets the currently active recording of the specified type in the thread-local scope.

WARNING: this intentionally bypasses any drop/flush logic. This should only ever be used in cases where you know the batcher/sink threads have been lost such as in a forked process.

impl RecordingStream

pub fn clone_weak(&self) -> RecordingStream

Clones the RecordingStream without incrementing the refcount.

Useful e.g. if you want to make sure that a detached thread won’t prevent the RecordingStream from flushing during shutdown.

impl RecordingStream

pub fn new( info: StoreInfo, batcher_config: ChunkBatcherConfig, sink: Box<dyn LogSink> ) -> Result<RecordingStream, RecordingStreamError>

Creates a new RecordingStream with a given StoreInfo and LogSink.

You can create a StoreInfo with crate::new_store_info;

The StoreInfo is immediately sent to the sink in the form of a re_log_types::SetStoreInfo.

You can find sinks in crate::sink.

See also: RecordingStreamBuilder.

pub fn disabled() -> RecordingStream

Creates a new no-op RecordingStream that drops all logging messages, doesn’t allocate any memory and doesn’t spawn any threads.

Self::is_enabled will return false.

impl RecordingStream

pub fn log( &self, ent_path: impl Into<EntityPath>, as_components: &impl AsComponents ) -> Result<(), RecordingStreamError>

Log data to Rerun.

This is the main entry point for logging data to rerun. It can be used to log anything that implements the AsComponents, such as any archetype or individual component.

The data will be timestamped automatically based on the RecordingStream’s internal clock. See RecordingStream::set_time_sequence etc for more information.

The entity path can either be a string (with special characters escaped, split on unescaped slashes) or an EntityPath constructed with crate::entity_path. See https://www.rerun.io/docs/concepts/entity-path for more on entity paths.

See also: Self::log_static for logging static data.

Internally, the stream will automatically micro-batch multiple log calls to optimize transport. See SDK Micro Batching for more information.

Example:

rec.log(
    "my/points",
    &rerun::Points3D::new([(0.0, 0.0, 0.0), (1.0, 1.0, 1.0)]),
)?;

pub fn send_columns<'a>( &self, ent_path: impl Into<EntityPath>, timelines: impl IntoIterator<Item = TimeColumn>, components: impl IntoIterator<Item = &'a dyn ComponentBatch<Name = ComponentName>> ) -> Result<(), RecordingStreamError>

Lower-level logging API to provide data spanning multiple timepoints.

Unlike the regular log API, which is row-oriented, this API lets you submit the data in a columnar form. The lengths of all of the TimeColumn and the component batches must match. All data that occurs at the same index across the different time and components arrays will act as a single logical row.

Note that this API ignores any stateful time set on the log stream via the Self::set_timepoint/Self::set_time_nanos/etc. APIs. Furthermore, this will not inject the default timelines log_tick and log_time timeline columns.

TODO(#7167): Unlike Python and C++, this API does not yet support arbitrary partitions of the incoming component arrays. Each component will be individually associated with a single timepoint, rather than offering how big the component arrays are that are associated with each timepoint.

pub fn log_static( &self, ent_path: impl Into<EntityPath>, as_components: &impl AsComponents ) -> Result<(), RecordingStreamError>

Log data to Rerun.

It can be used to log anything that implements the AsComponents, such as any archetype or individual component.

Static data has no time associated with it, exists on all timelines, and unconditionally shadows any temporal data of the same type. All timestamp data associated with this message will be dropped right before sending it to Rerun.

This is most often used for rerun::ViewCoordinates and rerun::AnnotationContext.

Internally, the stream will automatically micro-batch multiple log calls to optimize transport. See SDK Micro Batching for more information.

See also Self::log.

pub fn log_with_static( &self, ent_path: impl Into<EntityPath>, static_: bool, as_components: &impl AsComponents ) -> Result<(), RecordingStreamError>

Logs the contents of a component bundle into Rerun.

If static_ is set to true, all timestamp data associated with this message will be dropped right before sending it to Rerun. Static data has no time associated with it, exists on all timelines, and unconditionally shadows any temporal data of the same type.

Otherwise, the data will be timestamped automatically based on the RecordingStream’s internal clock. See RecordingStream::set_time_* family of methods for more information.

The entity path can either be a string (with special characters escaped, split on unescaped slashes) or an EntityPath constructed with crate::entity_path. See https://www.rerun.io/docs/concepts/entity-path for more on entity paths.

Internally, the stream will automatically micro-batch multiple log calls to optimize transport. See SDK Micro Batching for more information.

pub fn log_component_batches<'a>( &self, ent_path: impl Into<EntityPath>, static_: bool, comp_batches: impl IntoIterator<Item = &'a dyn ComponentBatch<Name = ComponentName>> ) -> Result<(), RecordingStreamError>

Logs a set of ComponentBatches into Rerun.

If static_ is set to true, all timestamp data associated with this message will be dropped right before sending it to Rerun. Static data has no time associated with it, exists on all timelines, and unconditionally shadows any temporal data of the same type.

Otherwise, the data will be timestamped automatically based on the RecordingStream’s internal clock. See RecordingStream::set_time_* family of methods for more information.

The number of instances will be determined by the longest batch in the bundle.

The entity path can either be a string (with special characters escaped, split on unescaped slashes) or an EntityPath constructed with crate::entity_path. See https://www.rerun.io/docs/concepts/entity-path for more on entity paths.

Internally, the stream will automatically micro-batch multiple log calls to optimize transport. See SDK Micro Batching for more information.

pub fn log_file_from_path( &self, filepath: impl AsRef<Path>, entity_path_prefix: Option<EntityPath>, static_: bool ) -> Result<(), RecordingStreamError>

Logs the file at the given path using all re_data_loader::DataLoaders available.

A single path might be handled by more than one loader.

This method blocks until either at least one re_data_loader::DataLoader starts streaming data in or all of them fail.

See https://www.rerun.io/docs/reference/data-loaders/overview for more information.

pub fn log_file_from_contents( &self, filepath: impl AsRef<Path>, contents: Cow<'_, [u8]>, entity_path_prefix: Option<EntityPath>, static_: bool ) -> Result<(), RecordingStreamError>

Logs the given contents using all re_data_loader::DataLoaders available.

A single path might be handled by more than one loader.

This method blocks until either at least one re_data_loader::DataLoader starts streaming data in or all of them fail.

See https://www.rerun.io/docs/reference/data-loaders/overview for more information.

impl RecordingStream

pub fn is_enabled(&self) -> bool

Check if logging is enabled on this RecordingStream.

If not, all recording calls will be ignored.

pub fn store_info(&self) -> Option<StoreInfo>

The StoreInfo associated with this RecordingStream.

pub fn is_forked_child(&self) -> bool

Determine whether a fork has happened since creating this RecordingStream. In general, this means our batcher/sink threads are gone and all data logged since the fork has been dropped.

It is essential that crate::cleanup_if_forked_child be called after forking the process. SDK-implementations should do this during their initialization phase.

impl RecordingStream

pub fn record_msg(&self, msg: LogMsg)

Records an arbitrary LogMsg.

pub fn record_row( &self, entity_path: EntityPath, row: PendingRow, inject_time: bool )

Records a single PendingRow.

If inject_time is set to true, the row’s timestamp data will be overridden using the RecordingStream’s internal clock.

Internally, incoming PendingRows are automatically coalesced into larger Chunks to optimize for transport.

pub fn log_chunk(&self, chunk: Chunk)

Logs a single Chunk.

Will inject log_tick and log_time timeline columns into the chunk. If you don’t want to inject these, use Self::send_chunk instead.

pub fn send_chunk(&self, chunk: Chunk)

Records a single Chunk.

This will not inject log_tick and log_time timeline columns into the chunk, for that use Self::log_chunk.

pub fn set_sink(&self, sink: Box<dyn LogSink>)

Swaps the underlying sink for a new one.

This guarantees that:

1. all pending rows and chunks are batched, collected and sent down the current sink,
2. the current sink is flushed if it has pending data in its buffers,
3. the current sink’s backlog, if there’s any, is forwarded to the new sink.

When this function returns, the calling thread is guaranteed that all future record calls will end up in the new sink.

Data loss

If the current sink is in a broken state (e.g. a TCP sink with a broken connection that cannot be repaired), all pending data in its buffers will be dropped.

pub fn flush_async(&self)

Initiates a flush of the pipeline and returns immediately.

This does not wait for the flush to propagate (see Self::flush_blocking). See RecordingStream docs for ordering semantics and multithreading guarantees.

pub fn flush_blocking(&self)

Initiates a flush the batching pipeline and waits for it to propagate.

See RecordingStream docs for ordering semantics and multithreading guarantees.

impl RecordingStream

pub fn connect(&self)

Swaps the underlying sink for a crate::log_sink::TcpSink sink pre-configured to use the specified address.

See also Self::connect_opts if you wish to configure the TCP connection.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn connect_opts(&self, addr: SocketAddr, flush_timeout: Option<Duration>)

Swaps the underlying sink for a crate::log_sink::TcpSink sink pre-configured to use the specified address.

flush_timeout is the minimum time the TcpSink will wait during a flush before potentially dropping data. Note: Passing None here can cause a call to flush to block indefinitely if a connection cannot be established.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn spawn(&self) -> Result<(), RecordingStreamError>

Spawns a new Rerun Viewer process from an executable available in PATH, then swaps the underlying sink for a crate::log_sink::TcpSink sink pre-configured to send data to that new process.

If a Rerun Viewer is already listening on this TCP port, the stream will be redirected to that viewer instead of starting a new one.

See also Self::spawn_opts if you wish to configure the behavior of thew Rerun process as well as the underlying TCP connection.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn spawn_opts( &self, opts: &SpawnOptions, flush_timeout: Option<Duration> ) -> Result<(), RecordingStreamError>

Spawns a new Rerun Viewer process from an executable available in PATH, then swaps the underlying sink for a crate::log_sink::TcpSink sink pre-configured to send data to that new process.

If a Rerun Viewer is already listening on this TCP port, the stream will be redirected to that viewer instead of starting a new one.

The behavior of the spawned Viewer can be configured via opts. If you’re fine with the default behavior, refer to the simpler Self::spawn.

flush_timeout is the minimum time the TcpSink will wait during a flush before potentially dropping data. Note: Passing None here can cause a call to flush to block indefinitely if a connection cannot be established.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn memory(&self) -> MemorySinkStorage

Swaps the underlying sink for a crate::sink::MemorySink sink and returns the associated MemorySinkStorage.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn binary_stream( &self ) -> Result<BinaryStreamStorage, BinaryStreamSinkError>

Swaps the underlying sink for a crate::sink::BinaryStreamSink sink and returns the associated BinaryStreamStorage.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn save(&self, path: impl Into<PathBuf>) -> Result<(), FileSinkError>

Swaps the underlying sink for a crate::sink::FileSink at the specified path.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn save_opts(&self, path: impl Into<PathBuf>) -> Result<(), FileSinkError>

Swaps the underlying sink for a crate::sink::FileSink at the specified path.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

If a blueprint was provided, it will be stored first in the file. Blueprints are currently an experimental part of the Rust SDK.

pub fn stdout(&self) -> Result<(), FileSinkError>

Swaps the underlying sink for a crate::sink::FileSink pointed at stdout.

If there isn’t any listener at the other end of the pipe, the RecordingStream will default back to buffered mode, in order not to break the user’s terminal.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn stdout_opts(&self) -> Result<(), FileSinkError>

Swaps the underlying sink for a crate::sink::FileSink pointed at stdout.

If there isn’t any listener at the other end of the pipe, the RecordingStream will default back to buffered mode, in order not to break the user’s terminal.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

If a blueprint was provided, it will be stored first in the file. Blueprints are currently an experimental part of the Rust SDK.

pub fn disconnect(&self)

Swaps the underlying sink for a crate::sink::BufferedSink.

This is a convenience wrapper for Self::set_sink that upholds the same guarantees in terms of data durability and ordering. See Self::set_sink for more information.

pub fn send_blueprint( &self, blueprint: Vec<LogMsg>, activation_cmd: BlueprintActivationCommand )

Send a blueprint through this recording stream

impl RecordingStream

pub fn now(&self) -> TimePoint

Returns the current time of the recording on the current thread.

pub fn set_timepoint(&self, timepoint: impl Into<TimePoint>)

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

There is no requirement of monotonicity. You can move the time backwards if you like.

See also:

• Self::set_time_sequence
• Self::set_time_seconds
• Self::set_time_nanos
• Self::disable_timeline
• Self::reset_time

pub fn set_time_sequence( &self, timeline: impl Into<TimelineName>, sequence: impl Into<i64> )

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time_sequence("frame_nr", frame_nr). You can remove a timeline again using rec.disable_timeline("frame_nr").

There is no requirement of monotonicity. You can move the time backwards if you like.

See also:

• Self::set_timepoint
• Self::set_time_seconds
• Self::set_time_nanos
• Self::disable_timeline
• Self::reset_time

pub fn set_time_seconds( &self, timeline: impl Into<TimelineName>, seconds: impl Into<f64> )

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time_seconds("sim_time", sim_time_secs). You can remove a timeline again using rec.disable_timeline("sim_time").

There is no requirement of monotonicity. You can move the time backwards if you like.

See also:

• Self::set_timepoint
• Self::set_time_sequence
• Self::set_time_nanos
• Self::disable_timeline
• Self::reset_time

pub fn set_time_nanos( &self, timeline: impl Into<TimelineName>, ns: impl Into<i64> )

Set the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.set_time_nanos("sim_time", sim_time_nanos). You can remove a timeline again using rec.disable_timeline("sim_time").

There is no requirement of monotonicity. You can move the time backwards if you like.

See also:

• Self::set_timepoint
• Self::set_time_sequence
• Self::set_time_seconds
• Self::disable_timeline
• Self::reset_time

pub fn disable_timeline(&self, timeline: impl Into<TimelineName>)

Clears out the current time of the recording for the specified timeline, for the current calling thread.

For example: rec.disable_timeline("frame"), rec.disable_timeline("sim_time").

See also:

• Self::set_timepoint
• Self::set_time_sequence
• Self::set_time_seconds
• Self::set_time_nanos
• Self::reset_time

pub fn reset_time(&self)

Clears out the current time of the recording, for the current calling thread.

Used for all subsequent logging performed from this same thread, until the next call to one of the time setting methods.

For example: rec.reset_time().

See also:

• Self::set_timepoint
• Self::set_time_sequence
• Self::set_time_seconds
• Self::set_time_nanos
• Self::disable_timeline

Trait Implementations

impl Clone for RecordingStream

fn clone(&self) -> RecordingStream

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RecordingStream

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

Formats the value using the given formatter.

impl Drop for RecordingStream

fn drop(&mut self)

Executes the destructor for this type.