up_rust/zero_copy/
rx.rs

1/********************************************************************************
2 * Copyright (c) 2026 Contributors to the Eclipse Foundation
3 *
4 * See the NOTICE file(s) distributed with this work for additional
5 * information regarding copyright ownership.
6 *
7 * This program and the accompanying materials are made available under the
8 * terms of the Apache License Version 2.0 which is available at
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 ********************************************************************************/
13
14use super::*;
15
16pub use crate::frame::view::{validate_frame_view_for_transport, UFrameView};
17
18/// *Role: a received payload read in place; dropping it returns the storage — see the [trait map](crate::guide::trait_map).*
19///
20/// Receive-side zero-copy frame lease returned by a transport.
21pub trait UZeroCopyRxLease: UFrameView {}
22
23/// *Role: a receive lease over contiguous loan-backed storage; lets typed payloads be borrowed without copying — see the [trait map](crate::guide::trait_map).*
24///
25/// Receive lease that can expose a contiguous payload from loan-backed storage.
26pub trait ULoanedContiguousZeroCopyRxFrame: UZeroCopyRxLease {
27    /// Returns one contiguous loan-backed application payload view.
28    ///
29    /// Implementations must not allocate, copy, or coalesce payload bytes to
30    /// satisfy this method.
31    fn loaned_contiguous_payload(&self) -> Result<LoanedPayload<'_>, UWireError>;
32
33    /// Returns diagnostic provenance for successful loaned payload borrows.
34    fn payload_loan_provenance(&self) -> Result<PayloadLoanProvenance, UWireError> {
35        Ok(self.loaned_contiguous_payload()?.provenance())
36    }
37
38    /// Returns only loan-backed contiguous payload bytes.
39    fn try_loaned_contiguous_payload(&self) -> Result<&[u8], UWireError> {
40        Ok(self.loaned_contiguous_payload()?.as_bytes())
41    }
42
43    /// Borrows one stable-container value from loan-backed contiguous storage.
44    fn borrow_stable_payload<T>(&self) -> Result<&T, UWireError>
45    where
46        T: StablePayload,
47    {
48        self.borrow_payload_as::<StableContainerPayload<T>, T>()
49    }
50
51    /// Borrows one typed value from loan-backed contiguous storage using codec `C`.
52    ///
53    /// This is the low-level codec-selected receive form. Selected-wire receive
54    /// wrappers expose a wire-selected `borrow_payload` helper so ordinary callers
55    /// do not need to name `C`.
56    fn borrow_payload_as<C, T>(&self) -> Result<&T, UWireError>
57    where
58        C: BorrowPayload<T>,
59    {
60        C::verify_encoding(self.metadata().payload_encoding())?;
61        if !self.has_payload() {
62            return Err(UWireError::MissingPayload);
63        }
64        let payload = self.loaned_contiguous_payload()?;
65        C::borrow_payload(payload.as_bytes())
66    }
67}
68
69/// *Role: implemented by applications to receive zero-copy leases — see the [trait map](crate::guide::trait_map).*
70///
71/// A handler for processing zero-copy receive leases.
72#[async_trait]
73pub trait UZeroCopyListener<Rx>: Send + Sync
74where
75    Rx: UZeroCopyRxLease + Send + 'static,
76{
77    /// Handles one received zero-copy frame lease.
78    async fn on_receive_zero_copy(&self, frame: Rx);
79}
up_rust/zero_copy/rx.rs

up_rust/zero_copy/
rx.rs
