Struct WriteOp 

pub struct WriteOp<'a> { /* private fields */ }

One item being written: a tensor or a whole composite.

Borrowing both the core and the caller’s payloads for its lifetime is what enforces ADR-041 § 3’s ownership rule in the type system — the core cannot hold a payload pointer after the operation ends, because the operation is what holds them.

Examples

See StreamWriterCore.

Implementations

impl WriteOp<'_>

pub fn step(&mut self) -> Result<WriteStep>

Advances the operation and returns what it needs next. Never blocks.

Errors

• Error::Core — a member descriptor does not encode
• Error::CoreFailed — a previous call ended this operation
• Error::CoreUnusable — the core was poisoned mid-item

Examples

See StreamWriterCore.

pub fn output_src(&self) -> &[u8]

The bytes to write for the outstanding WriteStep::Output request.

Either the staged descriptor or one of the caller’s payload slices — never a copy of them, and never a concatenation (ADR-041 § 3).

Examples

See StreamWriterCore.

pub fn report_written(&mut self, n: usize) -> Result<()>

Reports that the sink accepted n bytes of output_src.

A short write re-offers the remainder.

Errors

• Error::ZeroLengthWrite — n == 0, which § 4 forbids treating as progress. A sink that cannot accept bytes is reported with report_sink_closed instead.
• Error::InvalidProgressReport — more bytes reported than were offered. An unknown number of payload bytes is then on the wire and cannot be un-sent, so this poisons the core and its sink (ADR-041 § 6a).

Examples

See StreamWriterCore.

pub fn emitted(&self) -> u64

Bytes of this item already accepted by the sink, padding included.

Zero means nothing of the item has left the driver, which is exactly when the item may be resubmitted after a failure (§ 6b).

Examples

use hurray_core::{
    BufferHandle, DeviceTag, ElementType, LayoutDescriptor, Shape, SyncMode,
    TensorDescriptor, MIN_BUFFER_ALIGNMENT,
};
use hurray_io::stream::StreamWriterCore;

let handle =
    BufferHandle::new(8, MIN_BUFFER_ALIGNMENT, DeviceTag::Cpu, SyncMode::ProducerSynced)?;
let descriptor = TensorDescriptor::new(
    1, 0, ElementType::Float64, Shape::new(vec![1u64])?, 0,
    LayoutDescriptor::RowMajor, vec![handle], None, None, None, None,
)?;
let payload = [1u8; 8];
let buffers: [&[u8]; 1] = [&payload];

let mut core = StreamWriterCore::new();
let mut op = core.tensor(&descriptor, &buffers)?;
// Stepping offers bytes; only a report counts them.
op.step()?;
assert_eq!(op.emitted(), 0);

op.report_written(3)?;
assert_eq!(op.emitted(), 3);

pub fn report_sink_closed(&mut self) -> Error

Declares the sink closed while this item is in flight.

Returns the error to propagate. A partially written item is already on the wire and a stream cannot be un-sent, so this poisons the core as well: a fresh writer over the same connection is not a recovery (ADR-041 § 6a).

Examples

See mark_unusable.

pub fn mark_unusable(&mut self)

Marks the core unusable: a write moved bytes whose count was lost.

The read side’s equivalent damages only the core’s own position; here the bytes are already on the wire, so the sink is poisoned too (ADR-041 § 6a).

Examples

use hurray_io::stream::StreamWriterCore;

let mut core = StreamWriterCore::new();
let mut op = core.tensor(&descriptor, &buffers)?;
op.mark_unusable();
drop(op);

// The poison outlives the operation: this sink is not reusable.
assert!(core.is_unusable());
assert!(core.tensor(&descriptor, &buffers).is_err());