Trait smoldot_light::platform::PlatformRef

pub trait PlatformRef:
    UnwindSafe
    + Clone
    + Send
    + Sync
    + 'static {
    type Delay: Future<Output = ()> + Send + 'static;
    type Instant: Clone + Add<Duration, Output = Self::Instant> + Sub<Self::Instant, Output = Duration> + PartialOrd + Ord + PartialEq + Eq + Send + Sync + 'static;
    type MultiStream: Send + Sync + 'static;
    type Stream: Send + 'static;
    type ReadWriteAccess<'a>: DerefMut<Target = ReadWrite<Self::Instant>> + 'a;
    type StreamErrorRef<'a>: Display + Debug;
    type StreamConnectFuture: Future<Output = Self::Stream> + Send + 'static;
    type MultiStreamConnectFuture: Future<Output = MultiStreamWebRtcConnection<Self::MultiStream>> + Send + 'static;
    type StreamUpdateFuture<'a>: Future<Output = ()> + Send + 'a;
    type NextSubstreamFuture<'a>: Future<Output = Option<(Self::Stream, SubstreamDirection)>> + Send + 'a;

    // Required methods
    fn now_from_unix_epoch(&self) -> Duration;
    fn now(&self) -> Self::Instant;
    fn fill_random_bytes(&self, buffer: &mut [u8]);
    fn sleep(&self, duration: Duration) -> Self::Delay;
    fn sleep_until(&self, when: Self::Instant) -> Self::Delay;
    fn spawn_task(
        &self,
        task_name: Cow<'_, str>,
        task: impl Future<Output = ()> + Send + 'static,
    );
    fn log<'a>(
        &self,
        log_level: LogLevel,
        log_target: &'a str,
        message: &'a str,
        key_values: impl Iterator<Item = (&'a str, &'a dyn Display)>,
    );
    fn client_name(&self) -> Cow<'_, str>;
    fn client_version(&self) -> Cow<'_, str>;
    fn supports_connection_type(&self, connection_type: ConnectionType) -> bool;
    fn connect_stream(&self, address: Address<'_>) -> Self::StreamConnectFuture;
    fn connect_multistream(
        &self,
        address: MultiStreamAddress<'_>,
    ) -> Self::MultiStreamConnectFuture;
    fn open_out_substream(&self, connection: &mut Self::MultiStream);
    fn next_substream<'a>(
        &self,
        connection: &'a mut Self::MultiStream,
    ) -> Self::NextSubstreamFuture<'a>;
    fn read_write_access<'a>(
        &self,
        stream: Pin<&'a mut Self::Stream>,
    ) -> Result<Self::ReadWriteAccess<'a>, Self::StreamErrorRef<'a>>;
    fn wait_read_write_again<'a>(
        &self,
        stream: Pin<&'a mut Self::Stream>,
    ) -> Self::StreamUpdateFuture<'a>;
}

Access to a platform’s capabilities.

Implementations of this trait are expected to be cheaply-clonable “handles”. All clones of the same platform share the same objects. For instance, it is legal to create clone a platform, then create a connection on one clone, then access this connection on the other clone.

Required Associated Types

type Delay: Future<Output = ()> + Send + 'static

Future that resolves once a certain amount of time has passed or a certain point in time is reached. See PlatformRef::sleep and PlatformRef::sleep_until.

type Instant: Clone + Add<Duration, Output = Self::Instant> + Sub<Self::Instant, Output = Duration> + PartialOrd + Ord + PartialEq + Eq + Send + Sync + 'static

A certain point in time. Typically std::time::Instant, but one can also use core::time::Duration.

The implementations of the Add and Sub traits must panic in case of overflow or underflow, similar to the ones of std::time::Instant and core::time::Duration.

type MultiStream: Send + Sync + 'static

A multi-stream connection.

This object is merely a handle. The underlying connection should be dropped only after the MultiStream and all its associated substream objects (PlatformRef::Stream) have been dropped.

type Stream: Send + 'static

Opaque object representing either a single-stream connection or a substream in a multi-stream connection.

If this object is abruptly dropped, the underlying single stream connection or substream should be abruptly dropped (i.e. RST) as well, unless its reading and writing sides have been gracefully closed in the past.

type ReadWriteAccess<'a>: DerefMut<Target = ReadWrite<Self::Instant>> + 'a

Object that dereferences to read_write::ReadWrite and gives access to the stream’s buffers. See the read_write module for more information. See also PlatformRef::read_write_access.

type StreamErrorRef<'a>: Display + Debug

Reference to an error that happened on a stream.

Potentially returned by PlatformRef::read_write_access.

Typically &'a std::io::Error.

type StreamConnectFuture: Future<Output = Self::Stream> + Send + 'static

Future returned by PlatformRef::connect_stream.

type MultiStreamConnectFuture: Future<Output = MultiStreamWebRtcConnection<Self::MultiStream>> + Send + 'static

Future returned by PlatformRef::connect_multistream.

type StreamUpdateFuture<'a>: Future<Output = ()> + Send + 'a

Future returned by PlatformRef::wait_read_write_again.

type NextSubstreamFuture<'a>: Future<Output = Option<(Self::Stream, SubstreamDirection)>> + Send + 'a

Future returned by PlatformRef::next_substream.

Required Methods

fn now_from_unix_epoch(&self) -> Duration

Returns the time elapsed since the Unix Epoch (i.e. 00:00:00 UTC on 1 January 1970), ignoring leap seconds.

Panic

Panics if the system time is configured to be below the UNIX epoch. This situation is a very very niche edge case that isn’t worth handling.

fn now(&self) -> Self::Instant

Returns an object that represents “now”.

fn fill_random_bytes(&self, buffer: &mut [u8])

The given buffer must be completely filled with pseudo-random bytes.

Panic

Must panic if for some reason it is not possible to fill the buffer.

fn sleep(&self, duration: Duration) -> Self::Delay

Creates a future that becomes ready after at least the given duration has elapsed.

fn sleep_until(&self, when: Self::Instant) -> Self::Delay

Creates a future that becomes ready after the given instant has been reached.

fn spawn_task( &self, task_name: Cow<'_, str>, task: impl Future<Output = ()> + Send + 'static, )

Spawns a task that runs indefinitely in the background.

The first parameter is the name of the task, which can be useful for debugging purposes.

The Future must be run until it yields a value.

Implementers should be aware of the fact that polling the Future might panic (never intentionally, but in case of a bug). Many tasks can be restarted if they panic, and implementers are encouraged to absorb the panics that happen when polling. If a panic happens, the Future that has panicked must never be polled again.

Note: Ideally, the task parameter would require the UnwindSafe trait. Unfortunately, at the time of writing of this comment, it is extremely difficult if not impossible to implement this trait on Futures. It is for the same reason that the std::thread::spawn function of the standard library doesn’t require its parameter to implement UnwindSafe.

fn log<'a>( &self, log_level: LogLevel, log_target: &'a str, message: &'a str, key_values: impl Iterator<Item = (&'a str, &'a dyn Display)>, )

Emit a log line.

The log_level and log_target can be used in order to filter desired log lines.

The message is typically a short constant message indicating the nature of the log line. The key_values are a list of keys and values that are the parameters of the log message.

For example, message can be "block-announce-received" and key_values can contain the entries ("block_hash", ...) and ("sender", ...).

At the time of writing of this comment, message can also be a message written in plain english and destined to the user of the library. This might disappear in the future.

fn client_name(&self) -> Cow<'_, str>

Value returned when a JSON-RPC client requests the name of the client, or when a peer performs an identification request. Reasonable value is env!("CARGO_PKG_NAME").

fn client_version(&self) -> Cow<'_, str>

Value returned when a JSON-RPC client requests the version of the client, or when a peer performs an identification request. Reasonable value is env!("CARGO_PKG_VERSION").

fn supports_connection_type(&self, connection_type: ConnectionType) -> bool

Returns true if PlatformRef::connect_stream or PlatformRef::connect_multistream accepts a connection of the corresponding type.

Note: This function is meant to be pure. Implementations are expected to always return the same value for the same ConnectionType input. Enabling or disabling certain connection types after start-up is not supported.

fn connect_stream(&self, address: Address<'_>) -> Self::StreamConnectFuture

Starts a connection attempt to the given address.

This function is only ever called with an address of a type for which PlatformRef::supports_connection_type returned true in the past.

This function returns a Future. This Future must return as soon as possible, and must not wait for the connection to be established. In most scenarios, the Future returned by this function should immediately produce an output.

Panic

The function implementation panics if Address is of a type for which PlatformRef::supports_connection_type returns false.

fn connect_multistream( &self, address: MultiStreamAddress<'_>, ) -> Self::MultiStreamConnectFuture

Starts a connection attempt to the given address.

This function is only ever called with an address of a type for which PlatformRef::supports_connection_type returned true in the past.

Note: A so-called “multistream connection” is a connection made of multiple substreams, and for which the opening and closing or substreams is handled by the environment rather than by smoldot itself. Most platforms do not need to support multistream connections. This function is in practice used in order to support WebRTC connections when embedding smoldot-light within a web browser.

This function returns a Future. This Future must return as soon as possible, and must not wait for the connection to be established. In most scenarios, the Future returned by this function should immediately produce an output.

Panic

The function implementation panics if MultiStreamAddress is of a type for which PlatformRef::supports_connection_type returns false.

fn open_out_substream(&self, connection: &mut Self::MultiStream)

Queues the opening of an additional outbound substream.

The substream, once opened, must be yielded by PlatformRef::next_substream.

Calls to this function should be ignored if the connection has already been killed by the remote.

Note: No mechanism exists in this API to handle the situation where a substream fails to open, as this is not supposed to happen. If you need to handle such a situation, either try again opening a substream again or reset the entire connection.

fn next_substream<'a>( &self, connection: &'a mut Self::MultiStream, ) -> Self::NextSubstreamFuture<'a>

Waits until a new incoming substream arrives on the connection.

This returns both inbound and outbound substreams. Outbound substreams should only be yielded once for every call to PlatformRef::open_out_substream.

The future can also return None if the connection has been killed by the remote. If the future returns None, the user of the PlatformRef should drop the MultiStream and all its associated Streams as soon as possible.

fn read_write_access<'a>( &self, stream: Pin<&'a mut Self::Stream>, ) -> Result<Self::ReadWriteAccess<'a>, Self::StreamErrorRef<'a>>

Returns an object that implements DerefMut<Target = ReadWrite>. The read_write::ReadWrite object allows the API user to read data from the stream and write data to the stream.

If the stream has been reset in the past, this function should return a reference to the error that happened.

See the documentation of read_write for more information

Note: The with_buffers module provides a helper to more easily implement this function.

fn wait_read_write_again<'a>( &self, stream: Pin<&'a mut Self::Stream>, ) -> Self::StreamUpdateFuture<'a>

Returns a future that becomes ready when PlatformRef::read_write_access should be called again on this stream.

Must always returned immediately if PlatformRef::read_write_access has never been called on this stream.

See the documentation of read_write for more information.

Note: The with_buffers module provides a helper to more easily implement this function.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl PlatformRef for Arc<DefaultPlatform>

type Delay = Map<Timer, fn(_: Instant)>

type Instant = Instant

type MultiStream = Infallible

type Stream = Stream

type StreamConnectFuture = Ready<<Arc<DefaultPlatform> as PlatformRef>::Stream>

type MultiStreamConnectFuture = Pending<MultiStreamWebRtcConnection<<Arc<DefaultPlatform> as PlatformRef>::MultiStream>>

type ReadWriteAccess<'a> = ReadWriteAccess<'a, Instant>

type StreamUpdateFuture<'a> = Pin<Box<dyn Future<Output = ()> + Send + 'a>>

type StreamErrorRef<'a> = &'a Error

type NextSubstreamFuture<'a> = Pending<Option<(<Arc<DefaultPlatform> as PlatformRef>::Stream, SubstreamDirection)>>

fn now_from_unix_epoch(&self) -> Duration

fn now(&self) -> Self::Instant

fn fill_random_bytes(&self, buffer: &mut [u8])

fn sleep(&self, duration: Duration) -> Self::Delay

fn sleep_until(&self, when: Self::Instant) -> Self::Delay

fn spawn_task( &self, _task_name: Cow<'_, str>, task: impl Future<Output = ()> + Send + 'static, )

fn log<'a>( &self, log_level: LogLevel, log_target: &'a str, message: &'a str, key_values: impl Iterator<Item = (&'a str, &'a dyn Display)>, )

fn client_name(&self) -> Cow<'_, str>

fn client_version(&self) -> Cow<'_, str>

fn supports_connection_type(&self, connection_type: ConnectionType) -> bool

fn connect_stream(&self, multiaddr: Address<'_>) -> Self::StreamConnectFuture

fn connect_multistream( &self, _address: MultiStreamAddress<'_>, ) -> Self::MultiStreamConnectFuture

fn open_out_substream(&self, c: &mut Self::MultiStream)

fn next_substream( &self, c: &mut Self::MultiStream, ) -> Self::NextSubstreamFuture<'_>

fn read_write_access<'a>( &self, stream: Pin<&'a mut Self::Stream>, ) -> Result<Self::ReadWriteAccess<'a>, &'a Error>

fn wait_read_write_again<'a>( &self, stream: Pin<&'a mut Self::Stream>, ) -> Self::StreamUpdateFuture<'a>

Implementors

impl<T: PlatformRef> PlatformRef for WithPrefix<T>

type Delay = <T as PlatformRef>::Delay

type Instant = <T as PlatformRef>::Instant

type MultiStream = <T as PlatformRef>::MultiStream

type Stream = <T as PlatformRef>::Stream

type ReadWriteAccess<'a> = <T as PlatformRef>::ReadWriteAccess<'a>

type StreamErrorRef<'a> = <T as PlatformRef>::StreamErrorRef<'a>

type StreamConnectFuture = <T as PlatformRef>::StreamConnectFuture

type MultiStreamConnectFuture = <T as PlatformRef>::MultiStreamConnectFuture

type StreamUpdateFuture<'a> = <T as PlatformRef>::StreamUpdateFuture<'a>

type NextSubstreamFuture<'a> = <T as PlatformRef>::NextSubstreamFuture<'a>