Struct rerun::RecordingStream

source ·
pub struct RecordingStream { /* private fields */ }
Expand description

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.

Implementations§

source§

impl RecordingStream

source

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.

source

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

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

source

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.

source

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.

source

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

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

source

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.

source

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.

source§

impl RecordingStream

source

pub fn new( info: StoreInfo, batcher_config: DataTableBatcherConfig, 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.

source

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.

source§

impl RecordingStream

source

pub fn log( &self, ent_path: impl Into<EntityPath>, arch: &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.

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

See also: Self::log_timeless for logging timeless 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)]),
)?;
source

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

Log data to Rerun.

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

Timeless data is present on all timelines and behaves as if it was recorded infinitely far into the past. 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.

source

pub fn log_with_timeless( &self, ent_path: impl Into<EntityPath>, timeless: bool, arch: &impl AsComponents ) -> Result<(), RecordingStreamError>

Logs the contents of a component bundle into Rerun.

If timeless is set to true, all timestamp data associated with this message will be dropped right before sending it to Rerun. Timeless data is present on all timelines and behaves as if it was recorded infinitely far into the past.

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

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

source

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

Logs a set of ComponentBatches into Rerun.

If timeless is set to false, all timestamp data associated with this message will be dropped right before sending it to Rerun. Timeless data is present on all timelines and behaves as if it was recorded infinitely far into the past.

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. All of the batches should have the same number of instances, or length 1 if the component is a splat, or 0 if the component is being cleared.

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

source§

impl RecordingStream

source

pub fn is_enabled(&self) -> bool

Check if logging is enabled on this RecordingStream.

If not, all recording calls will be ignored.

source

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

The StoreInfo associated with this RecordingStream.

source

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.

source§

impl RecordingStream

source

pub fn record_msg(&self, msg: LogMsg)

Records an arbitrary LogMsg.

source

pub fn record_row(&self, row: DataRow, inject_time: bool)

Records a single DataRow.

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

Internally, incoming DataRows are automatically coalesced into larger DataTables to optimize for transport.

source

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 tables 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.

source

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.

source

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.

source§

impl RecordingStream

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source§

impl RecordingStream

source

pub fn now(&self) -> TimePoint

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

source

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:

source

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:

source

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:

source

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:

source

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:

source

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:

Trait Implementations§

source§

impl Clone for RecordingStream

source§

fn clone(&self) -> RecordingStream

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for RecordingStream

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Az for T

source§

fn az<Dst>(self) -> Dstwhere T: Cast<Dst>,

Casts the value.
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<Src, Dst> CastFrom<Src> for Dstwhere Src: Cast<Dst>,

source§

fn cast_from(src: Src) -> Dst

Casts the value.
source§

impl<T> CheckedAs for T

source§

fn checked_as<Dst>(self) -> Option<Dst>where T: CheckedCast<Dst>,

Casts the value.
source§

impl<Src, Dst> CheckedCastFrom<Src> for Dstwhere Src: CheckedCast<Dst>,

source§

fn checked_cast_from(src: Src) -> Option<Dst>

Casts the value.
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

source§

impl<T> DynClone for Twhere T: Clone,

source§

fn __clone_box(&self, _: Private) -> *mut ()

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<Src, Dst> LosslessTryInto<Dst> for Srcwhere Dst: LosslessTryFrom<Src>,

source§

fn lossless_try_into(self) -> Option<Dst>

Performs the conversion.
source§

impl<Src, Dst> LossyInto<Dst> for Srcwhere Dst: LossyFrom<Src>,

source§

fn lossy_into(self) -> Dst

Performs the conversion.
source§

impl<T> OverflowingAs for T

source§

fn overflowing_as<Dst>(self) -> (Dst, bool)where T: OverflowingCast<Dst>,

Casts the value.
source§

impl<Src, Dst> OverflowingCastFrom<Src> for Dstwhere Src: OverflowingCast<Dst>,

source§

fn overflowing_cast_from(src: Src) -> (Dst, bool)

Casts the value.
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> SaturatingAs for T

source§

fn saturating_as<Dst>(self) -> Dstwhere T: SaturatingCast<Dst>,

Casts the value.
source§

impl<Src, Dst> SaturatingCastFrom<Src> for Dstwhere Src: SaturatingCast<Dst>,

source§

fn saturating_cast_from(src: Src) -> Dst

Casts the value.
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> UnwrappedAs for T

source§

fn unwrapped_as<Dst>(self) -> Dstwhere T: UnwrappedCast<Dst>,

Casts the value.
source§

impl<Src, Dst> UnwrappedCastFrom<Src> for Dstwhere Src: UnwrappedCast<Dst>,

source§

fn unwrapped_cast_from(src: Src) -> Dst

Casts the value.
§

impl<T> Upcast<T> for T

§

fn upcast(&self) -> Option<&T>

§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
source§

impl<T> WrappingAs for T

source§

fn wrapping_as<Dst>(self) -> Dstwhere T: WrappingCast<Dst>,

Casts the value.
source§

impl<Src, Dst> WrappingCastFrom<Src> for Dstwhere Src: WrappingCast<Dst>,

source§

fn wrapping_cast_from(src: Src) -> Dst

Casts the value.
§

impl<T> WasmNotSend for Twhere T: Send,

§

impl<T> WasmNotSync for Twhere T: Sync,