Struct IoRef 

pub struct IoRef(/* private fields */);

A cheap, cloneable handle to an Io connection.

All clones point to the same connection. Changes to its buffers, configuration, timers, errors, or shutdown state are visible through every clone. Cloning IoRef never clones the socket.

Use it to inspect the connection, access its buffers, queue output, or start graceful or immediate shutdown. These methods are also available directly on Io, which dereferences to IoRef.

Keeping an IoRef alive does not keep the connection open after its Io owner is dropped. Like Io, it stays on the local runtime thread and is neither Send nor Sync.

Implementations

impl IoRef

pub fn id(&self) -> Id

Gets the ID.

pub fn tag(&self) -> &'static str

Gets the I/O tag.

pub fn cfg(&self) -> &IoConfig

Gets the configuration.

pub fn shared(&self) -> SharedCfg

Gets the shared configuration.

pub fn is_active(&self) -> bool

Checks whether the I/O stream is active.

This becomes false as soon as the connection leaves its active state, whether it was closed locally, force-terminated, or the transport reported the peer as gone. Closing is not instantaneous, so buffered output may still be flushing and buffered input stays readable after this goes false; use is_closed to ask whether closing has finished.

pub fn is_read_eof(&self) -> bool

Checks whether the transport read half reached clean EOF.

Buffered input remains available and the write half may still be used.

pub fn is_closed(&self) -> bool

Checks whether the I/O stream is closed.

This becomes true once the backend released the underlying socket and transport teardown has finished, so nothing further can be read from or delivered to the peer. Every way a connection can end reaches this state, whether it closed gracefully, was force-terminated or the peer disappeared. Use is_active to also cover a close that is still in progress.

Buffered input that was already received stays readable.

pub fn is_rd_backpressure(&self) -> bool

Checks whether read back-pressure is enabled.

This becomes true once unread data in the application-facing read buffer reaches the configured high watermark, which parks the transport read task.

Two different paths release it. Consuming through decode, with_buf, with_read_src or with_read_dst releases it once the buffer has fallen to at most half the high watermark. Asking for more input through Io::poll_read_more, and the methods built on it, releases it immediately however much data is still buffered.

pub fn is_wr_backpressure(&self) -> bool

Checks whether write back-pressure is enabled.

This becomes true once outstanding output reaches the configured high watermark. Outstanding output includes buffered data and data that the transport owns but has not yet written to the peer. It is released once the outstanding size falls to half the high watermark.

Nothing enforces the signal: encoding continues to succeed while it is set. Producers that are not driven by a dispatcher should check this before encoding more, or the write buffer grows without bound. See encode and write_ready.

pub fn is_read_filter_paused(&self) -> bool

Checks whether transport reads are paused by the filter chain.

This is true while a filter is not ready for transport reads although the io state allows them, for example a filter that waits for its own resources. No input arrives during the pause, it is not caused by the peer, so read timeouts should not run. The dispatcher is notified when the pause starts and when it ends.

pub fn is_write_filter_paused(&self) -> bool

Checks whether transport writes are paused by the filter chain.

This is true while buffered output is waiting for a filter that is not ready for transport writes. Output does not drain during the pause, it is not caused by the peer, so write timeouts should not run. The dispatcher is notified when the pause starts and when it ends.

pub async fn write_ready(&self) -> Result<(), Error>

Waits until the write buffer can accept more output.

Completes immediately unless write back-pressure is enabled. While it is, waits until the outstanding output falls to the release threshold (half of the high watermark), the level at which the dispatcher releases back-pressure. Any number of tasks can wait at once, the write task wakes them without involving the dispatcher.

Producers that are not driven by a dispatcher can await this before encoding more, so the write buffer does not grow without bound.

Fails once the connection is closing or closed, and with io::ErrorKind::TimedOut if the write timeout is set and expires first.

pub fn close(&self)

Gracefully closes the connection.

Initiates the I/O stream shutdown process.

pub fn terminate(&self)

Force-closes the connection.

The dispatcher does not wait for incomplete responses. The I/O stream is terminated without any graceful period, and whatever is still buffered is discarded.

The transport aborts the connection instead of closing it gracefully, so the peer most likely observes an RST rather than a clean end of stream, and output that has not been acknowledged yet is lost. That is what keeps a truncated response distinguishable from a complete one, but it also means this must not be used to end a connection normally. Use close for that.

pub fn query<T>(&self) -> QueryItem<T>

where T: 'static,

Queries filter-specific data.

pub fn encode<U>( &self, item: <U as Encoder>::Item, codec: &U, ) -> Result<(), <U as Encoder>::Error>

where U: Encoder,

Encodes an item into the write buffer.

This method reports codec errors only. Any io::Error produced while buffering is discarded: if the connection is already closing or closed the item is not encoded, and a transport or filter error raised by an eager backend write is dropped. Such errors remain observable later through crate::Io::poll_flush or crate::Io::poll_recv. Use encode_slice or encode_bytes when they must be observed at the call site.

Back-pressure is advisory

Encoding never blocks and never refuses. Once buffered output reaches the configured high watermark this arms write back-pressure and wakes the dispatch task, but the item is still buffered and Ok is still returned. A caller that keeps encoding without consulting is_wr_backpressure, or awaiting Io::poll_status_update or Io::poll_flush, will grow the write buffer without bound, because a slow peer cannot slow the producer down on its own. Honouring the signal is the caller’s responsibility.

pub fn encode_slice(&self, src: &[u8]) -> Result<(), Error>

Encodes the slice into the write buffer.

If this triggers an eager backend write, any transport or filter error from that write is returned immediately.

Write back-pressure is advisory here too; see encode.

pub fn encode_bytes<B>(&self, src: B) -> Result<(), Error>

where BytePage: From<B>,

Writes bytes to the write buffer.

If this triggers an eager backend write, any transport or filter error from that write is returned immediately.

Write back-pressure is advisory here too; see encode.

pub fn decode<U>( &self, codec: &U, ) -> Result<Option<<U as Decoder>::Item>, <U as Decoder>::Error>

where U: Decoder,

Attempts to decode a frame from the read buffer.

Once the transport reached eof this uses Decoder::decode_eof instead of Decoder::decode.

This mutates the read state: it clears read readiness, and consuming enough bytes may release read backpressure. It also cancels a pause installed by Io::poll_read_pause and wakes the transport read task.

Decoded frames that share the read buffer’s allocation keep the whole buffer alive, see IoConfig::set_read_size.

pub fn decode_item<U>( &self, codec: &U, ) -> Result<Decoded<<U as Decoder>::Item>, <U as Decoder>::Error>

where U: Decoder,

Attempts to decode a frame from the read buffer.

Decoded::consumed reports the bytes taken by this attempt and Decoded::remains the bytes left in the application-facing read buffer. Once the transport reached eof this uses Decoder::decode_eof instead of Decoder::decode.

Like decode, this mutates the read state: it clears read readiness, may release read backpressure, and cancels a pause installed by Io::poll_read_pause.

pub fn send_buf(&self) -> Result<(), Error>

Sends the write buffer to the I/O layer.

Requires the underlying runtime to implement .write(); otherwise, no action is taken.

pub fn with_buf<F, R>(&self, f: F) -> Result<R, Error>

where F: FnOnce(&mut FilterBuf<'_>) -> R,

Provides temporary access to the outermost filter buffers.

Filter callbacks run before and after f, and any produced write data is scheduled for delivery after the closure returns. Errors from an eager backend write are returned to the caller.

The destination exposed by FilterBuf::with_read_buffers is the application-facing read destination, so consuming enough of it releases read backpressure and cancels an installed read pause.

Buffer access is not reentrant. The closure must not use this connection to access an overlapping read or write buffer, or change the filter chain.

pub fn with_read_dst<F, R>(&self, f: F) -> R

where F: FnOnce(&mut BytesMut) -> R,

Provides mutable access to the application-facing read destination.

This holds the decoded bytes the application consumes; see with_read_src for the transport-facing source.

This mutates the read state whether or not f consumes anything. While read back-pressure is active nothing is released until the buffer has fallen to at most half the high watermark, so until then read readiness and any installed read pause are left in place. Once it has, or when back-pressure was not active, read readiness is cleared and a pause installed by Io::poll_read_pause is cancelled, waking the transport read task.

Use crate::Io::poll_read_more rather than this method to check whether data is available.

The closure must not access this connection’s application-facing read destination again. Nested access is unsupported and may terminate the connection or lose nested buffer changes.

pub fn read_dst_size(&self) -> usize

Returns the size of the application-facing read destination.

Unlike with_read_dst this does not change the read state, read readiness, read back-pressure and an installed read pause are left in place, and no buffer is allocated. Returns 0 when called from inside with_read_dst.

pub fn with_write_src<F, R>(&self, f: F) -> Result<R, Error>

where F: FnOnce(&mut BytePages) -> R,

Provides mutable access to the application-facing write source.

This holds the bytes the application produces; see with_write_dst for the transport-facing destination.

Returns an error without invoking f if the connection is closing or closed. Data appended by f is scheduled for delivery. If that starts an eager backend write, its transport or filter error is returned.

Panics

Panics if the closure accesses the same application-facing write buffer again.

pub fn with_read_src<F, R>(&self, f: F) -> R

where F: FnOnce(&mut BytesMut) -> R,

Provides mutable access to the transport-facing read source.

This is the buffer the transport fills; it is the counterpart of the application-facing destination exposed by with_read_dst. Primarily intended for transport and filter implementations.

Without a filter installed this is the same buffer as the application-facing destination, so consuming enough of it releases read backpressure and cancels an installed read pause. Unlike with_read_dst it never clears read readiness.

The closure must not access this connection’s transport-facing read source again. Nested access is unsupported and may terminate the connection or lose nested buffer changes.

pub fn with_write_dst<F, R>(&self, f: F) -> R

where F: FnOnce(&mut BytePages) -> R,

Provides mutable access to the transport-facing write destination.

This is the buffer the transport drains; it is the counterpart of the application-facing source exposed by with_write_src. Primarily intended for transport and filter implementations.

Panics

Panics if the closure accesses the same transport-facing write buffer again.

pub fn notify_dispatcher(&self)

Wakeup dispatcher

pub fn notify_timeout(&self)

Wakeup dispatcher and send Timeout error

pub fn timer_handle(&self) -> TimerHandle

Returns the currently registered dispatcher timer handle.

TimerHandle::ZERO is returned when no timer is registered.

pub fn start_timer(&self, timeout: Seconds) -> TimerHandle

Starts or updates the dispatcher timer.

The timer uses second-granularity deadlines. When it expires, poll_status_update reports IoStatusUpdate::Timeout.

A zero timeout cancels the current timer but does not consume a timeout notification that has already been delivered. Use stop_timer when leaving a protocol phase to also clear such a notification.

pub fn stop_timer(&self)

Stops the timer and clears any pending timeout notification.

pub fn on_disconnect(&self) -> Waiter<'static>

Returns a future that resolves when the complete I/O stream disconnects.

A clean peer read EOF does not resolve this future because the write half remains usable. It resolves once the transport backend reports that teardown has finished, which happens after local shutdown or force termination. terminate requests that teardown but does not itself resolve the future.

pub fn wake(&self, tag: usize)

Wakes all Waiter waiters of the tag.

Tags reserved for internal use are ignored.

pub fn waiter(&self, tag: usize) -> Waiter<'_>

Creates a Waiter for the tag.

The waiter registers on its first poll.

Panics

Panics in debug builds if the tag is reserved for internal use, usize::MAX - 1 and usize::MAX - 2 are reserved.

Trait Implementations

impl<F> AsRef<IoRef> for Io<F>

fn as_ref(&self) -> &IoRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for IoRef

fn clone(&self) -> IoRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for IoRef

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

Formats the value using the given formatter.

impl Eq for IoRef

impl Hash for IoRef

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for IoRef

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

Equality operator ==.

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

Inequality operator !=.