silk/byte_duplex

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Partial reliable-byte input and output with explicit deadlines and directional shutdown.

When to use

Require ByteDuplex when a protocol driver owns its buffers and must acknowledge exact transport prefixes. Use silk.writer.Writer when each write is all-or-error.

Details

Each nonempty successful transfer reports one positive prefix. Bytes after that prefix remain with the caller. Deadlines are absolute marks from the active MonotonicClock provider. ReadTransfer.End is transport end. It is not a protocol close message.

Gotchas

An invalid provider count makes the lease unusable. A canceled external transfer can also make ownership ambiguous. Close such a lease and do not retry its last buffer.

Import as ByteDuplex with import silk.byte_duplex { ByteDuplex }.

Public declarations: 4.

ByteIoOperation

pub enum ByteIoOperation

The operation associated with one portable byte-I/O failure.

Read

Read = 0

A partial input transfer.

Write

Write = 1

A partial output transfer.

Flush

Flush = 2

A transport-boundary flush.

ShutdownWrite

ShutdownWrite = 3

A write-direction shutdown.

Close

Close = 4

A terminal duplex close.

ByteIoError

pub union ByteIoError

A typed failure from one ByteDuplex operation.

Timeout

ByteIoError.Timeout { operation: ByteIoOperation }: ByteIoError

The absolute monotonic deadline was reached.

Field operation

pub operation: ByteIoOperation

The operation that reached its deadline.

InvalidTransferCount

ByteIoError.InvalidTransferCount { operation: ByteIoOperation, count: usize, limit: usize }: ByteIoError

The provider reported an impossible successful prefix.

Field operation

pub operation: ByteIoOperation

The operation that reported the count.

Field count

pub count: usize

The count reported by the provider.

Field limit

pub limit: usize

The caller buffer length for that transfer.

Closed

ByteIoError.Closed { operation: ByteIoOperation }: ByteIoError

The requested direction or complete lease is closed.

Field operation

pub operation: ByteIoOperation

The operation rejected after closure.

Provider

ByteIoError.Provider { operation: ByteIoOperation, code: i32 }: ByteIoError

The provider rejected an otherwise valid operation.

Field operation

pub operation: ByteIoOperation

The rejected operation.

Field code

pub code: i32

One provider-defined diagnostic code.

ReadTransfer

pub union ReadTransfer

The result of one partial input operation.

Data

ReadTransfer.Data { count: usize }: ReadTransfer

A positive prefix of the output slice now contains input bytes.

Field count

pub count: usize

The exact initialized prefix length.

End

ReadTransfer.End: ReadTransfer

The underlying transport reached orderly end-of-input.

ByteDuplex

pub service ByteDuplex

Unsafe provider hooks for one exclusive reliable-byte transport.

Details

Ordinary callers use the safe inherent operations with the corresponding names. Provider implementations satisfy these hooks; calling one directly acknowledges that its raw transfer count has not passed the canonical boundary validation.

Operation readSomeRaw

unsafe effect<'life0> fn readSomeRaw<'life0>(output: &'life0 mut [u8], deadline: silk/option.Option<silk/system_clock.Instant>) -> ReadTransfer ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Performs one provider read before canonical transfer validation.

Operation writeSomeRaw

unsafe effect<'life0> fn writeSomeRaw<'life0>(input: &'life0 [u8], deadline: silk/option.Option<silk/system_clock.Instant>) -> usize ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Performs one provider write before canonical transfer validation.

Operation flushRaw

unsafe effect<'static> fn flushRaw(deadline: silk/option.Option<silk/system_clock.Instant>) -> () ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Performs the provider's transport-boundary flush.

Operation shutdownWriteRaw

unsafe effect<'static> fn shutdownWriteRaw(deadline: silk/option.Option<silk/system_clock.Instant>) -> () ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Closes only the provider's write direction after the canonical wrapper has flushed.

Operation closeRaw

unsafe effect<'static> fn closeRaw() -> () ! ByteIoError ? &mut ByteDuplex with Intrinsic.nonParking()

Closes the complete transport lease. Implementations must remain terminal and idempotent.

Associated function ByteDuplex.readSome

pub effect<'life0> fn readSome<'life0>(output: &'life0 mut [u8], deadline: silk/option.Option<silk/system_clock.Instant>) -> ReadTransfer ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Reads one positive prefix or reports orderly transport end.

Details

Empty output completes without calling the provider. An impossible provider count terminally closes the lease and returns InvalidTransferCount, even if that close itself fails.

Associated function ByteDuplex.writeSome

pub effect<'life0> fn writeSome<'life0>(input: &'life0 [u8], deadline: silk/option.Option<silk/system_clock.Instant>) -> usize ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Writes one positive prefix and returns its exact length.

Details

Empty input completes without calling the provider. An impossible provider count terminally closes the lease and returns InvalidTransferCount, even if that close itself fails.

Associated function ByteDuplex.flush

pub effect<'static> fn flush(deadline: silk/option.Option<silk/system_clock.Instant>) -> () ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Flushes accepted output to the provider's documented transport boundary.

Associated function ByteDuplex.shutdownWrite

pub effect<'static> fn shutdownWrite(deadline: silk/option.Option<silk/system_clock.Instant>) -> () ! ByteIoError ? &mut ByteDuplex | &mut MonotonicClock

Flushes accepted output and then closes only the write direction.

Associated function ByteDuplex.close

pub effect<'static> fn close() -> () ! ByteIoError ? &mut ByteDuplex

Closes the complete transport lease. Repeated calls remain terminal.

Associated function ByteDuplex.timeout

pub fn timeout(operation: ByteIoOperation) -> ByteIoError

Constructs a timeout failure for operation.

Associated function ByteDuplex.invalidTransferCount

pub fn invalidTransferCount(operation: ByteIoOperation, count: usize, limit: usize) -> ByteIoError

Constructs an invalid-count failure with the observed and permitted counts.

Associated function ByteDuplex.closed

pub fn closed(operation: ByteIoOperation) -> ByteIoError

Constructs a closed-direction failure for operation.

Associated function ByteDuplex.provider

pub fn provider(operation: ByteIoOperation, code: i32) -> ByteIoError

Constructs a provider failure with one provider-defined diagnostic code.