Browse the docs

silk.io.buffered_transfer.

Copy bytes from one buffered session to another, and consume only what the destination accepts.

When to use#

Use BufferedTransfer.transferAtMost or BufferedTransfer.transferExact inside silk.io.buffered_duplex.withBufferedPairCapacity to forward a body or a stream, for example in a proxy.

Details#

The transfer reads into the input buffer of the source and offers those bytes to the output buffer of the destination. It consumes from the source only the bytes that the destination accepted. If a write fails, the bytes that were not accepted stay unread in the source. No operation allocates.

Gotchas#

The destination output buffer can still hold bytes after the transfer. Flush the destination when the transfer is complete.

Import as BufferedTransfer with import silk.io.buffered_transfer { BufferedTransfer }.

Public declarations: 2.

TransferOutcome#

silk
pub struct TransferOutcome

The result of BufferedTransfer.transferAtMost.

Field count#

silk
pub count: usize

The number of bytes that the destination accepted and the source consumed.

Field endObserved#

silk
pub endObserved: bool

true if the transfer stopped because the source ended. false if it reached the limit.

BufferedTransfer#

silk
pub struct BufferedTransfer

The owner type of the transfer operations. It has no fields and is never constructed.

When to use#

Use BufferedTransfer.transferAtMost or BufferedTransfer.transferExact inside silk.io.buffered_duplex.withBufferedPairCapacity to forward a body or a stream, for example in a proxy.

Implementation BufferedTransfer#

silk
impl BufferedTransfer

Associated function transferAtMost#

silk
pub effect fn transferAtMost<'source, 'destination, SP, DP>(
  source: &mut BufferedDuplex<'source, SP>,
  destination: &mut BufferedDuplex<'destination, DP>,
  limit: usize,
  deadline: Option<Instant>,
) -> TransferOutcome
! BufferError
? &mut MonotonicClock
where &mut SP provides &ByteDuplex from &mut ByteDuplex | &mut MonotonicClock,
  &mut DP provides &ByteDuplex from &mut ByteDuplex | &mut MonotonicClock

Copies up to limit bytes from source to destination. It stops early if the source ends.

Details#

It reads into the input buffer of source and offers those bytes to the output buffer of destination. It consumes from source only the bytes that destination accepted. If a write fails, the bytes that were not accepted stay unread in source. Nothing allocates. deadline is an absolute time on the active MonotonicClock. Option.none() means no time limit. It applies to each read and write.

Errors#

  • BufferError.Terminal if an earlier failure or a close made a session unusable.

  • BufferError.ReadFailed if a read of source fails, or BufferError.WriteFailed if a write to destination fails. The failed session becomes terminal. progress and accepted include the bytes that this call already transferred.

Gotchas#

The output buffer of destination can still hold bytes after the transfer. Flush destination when the transfer is complete.

Associated function transferExact#

silk
pub effect fn transferExact<'source, 'destination, SP, DP>(
  source: &mut BufferedDuplex<'source, SP>,
  destination: &mut BufferedDuplex<'destination, DP>,
  count: usize,
  deadline: Option<Instant>,
) -> ()
! BufferError
? &mut MonotonicClock
where &mut SP provides &ByteDuplex from &mut ByteDuplex | &mut MonotonicClock,
  &mut DP provides &ByteDuplex from &mut ByteDuplex | &mut MonotonicClock

Copies exactly count bytes from source to destination.

Details#

It consumes from source only the bytes that destination accepted. If a write fails, the bytes that were not accepted stay unread in source. Nothing allocates. deadline is an absolute time on the active MonotonicClock. Option.none() means no time limit. It applies to each read and write.

Errors#

  • BufferError.UnexpectedEnd if the source ends first. progress gives the number of bytes that were transferred.

  • BufferError.Terminal if an earlier failure or a close made a session unusable.

  • BufferError.ReadFailed if a read of source fails, or BufferError.WriteFailed if a write to destination fails. The failed session becomes terminal. progress and accepted include the bytes that this call already transferred.

Gotchas#

The output buffer of destination can still hold bytes after the transfer. Flush destination when the transfer is complete.

Category: Input and output.

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

View the source of this page