Skip to main content

qubit_io_binary/ext/
async_leb128_read_ext.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Asynchronous LEB128 reads.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec_binary::Leb128Codec;
14use qubit_codec_binary::NonStrict;
15use qubit_codec_binary::Strict;
16use qubit_io::AsyncInput;
17
18use crate::util::read_leb128_payload_async;
19
20/// Reads one LEB128 payload and decodes it using the selected codec policy.
21macro_rules! read_leb128_value_async {
22    ($reader:expr, $ty:ty, $policy:ty) => {
23        read_leb128_payload_async::<
24            { Leb128Codec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
25            Leb128Codec<$ty, $policy>,
26            _,
27        >($reader)
28        .await
29    };
30}
31
32/// Defines an asynchronous extension method for one integer type and policy.
33macro_rules! leb128_read_method {
34    ($doc:literal, $name:ident, $ty:ty, $policy:ty) => {
35        #[doc = $doc]
36        #[doc = ""]
37        #[doc = "# Returns"]
38        #[doc = ""]
39        #[doc = concat!("Returns the decoded `", stringify!($ty), "`.")]
40        #[doc = ""]
41        #[doc = "# Errors"]
42        #[doc = ""]
43        #[doc = "Returns an input error or an invalid-data error when the \
44                 payload is malformed or violates the selected policy."]
45        #[doc = ""]
46        #[doc = "# Cancellation safety"]
47        #[doc = ""]
48        #[doc = "This operation is not cancellation safe. Dropping the future \
49                 retains any bytes already consumed from the input."]
50        #[inline(always)]
51        fn $name(&mut self) -> impl Future<Output = Result<$ty>> + '_
52        where
53            Self: Unpin,
54        {
55            async move { read_leb128_value_async!(self, $ty, $policy) }
56        }
57    };
58}
59
60/// Future-based LEB128 integer reads from runtime-neutral async inputs.
61///
62/// Target-width `usize` and `isize` formats remain platform dependent. Use
63/// fixed-width methods for persistent files and cross-platform protocols.
64///
65/// # Cancellation safety
66///
67/// These reads are not cancellation safe. Dropping a pending future leaves
68/// bytes already consumed from the input consumed.
69///
70/// # Examples
71///
72/// Define a generic async helper that reads a strict unsigned LEB128 value:
73///
74/// ```
75/// use qubit_io::AsyncInput;
76/// use qubit_io_binary::AsyncLeb128ReadExt;
77///
78/// async fn read_id<I>(input: &mut I) -> std::io::Result<u64>
79/// where
80///     I: AsyncInput<Item = u8> + Unpin,
81/// {
82///     input.read_uleb_u64_strict_async().await
83/// }
84/// ```
85pub trait AsyncLeb128ReadExt: AsyncInput<Item = u8> {
86    leb128_read_method!(
87        "Asynchronously reads a non-strict LEB128 `u8`.",
88        read_uleb_u8_non_strict_async,
89        u8,
90        NonStrict
91    );
92    leb128_read_method!(
93        "Asynchronously reads a strict LEB128 `u8`.",
94        read_uleb_u8_strict_async,
95        u8,
96        Strict
97    );
98    leb128_read_method!(
99        "Asynchronously reads a non-strict LEB128 `u16`.",
100        read_uleb_u16_non_strict_async,
101        u16,
102        NonStrict
103    );
104    leb128_read_method!(
105        "Asynchronously reads a strict LEB128 `u16`.",
106        read_uleb_u16_strict_async,
107        u16,
108        Strict
109    );
110    leb128_read_method!(
111        "Asynchronously reads a non-strict LEB128 `u32`.",
112        read_uleb_u32_non_strict_async,
113        u32,
114        NonStrict
115    );
116    leb128_read_method!(
117        "Asynchronously reads a strict LEB128 `u32`.",
118        read_uleb_u32_strict_async,
119        u32,
120        Strict
121    );
122    leb128_read_method!(
123        "Asynchronously reads a non-strict LEB128 `u64`.",
124        read_uleb_u64_non_strict_async,
125        u64,
126        NonStrict
127    );
128    leb128_read_method!(
129        "Asynchronously reads a strict LEB128 `u64`.",
130        read_uleb_u64_strict_async,
131        u64,
132        Strict
133    );
134    leb128_read_method!(
135        "Asynchronously reads a non-strict LEB128 `u128`.",
136        read_uleb_u128_non_strict_async,
137        u128,
138        NonStrict
139    );
140    leb128_read_method!(
141        "Asynchronously reads a strict LEB128 `u128`.",
142        read_uleb_u128_strict_async,
143        u128,
144        Strict
145    );
146    leb128_read_method!(
147        "Asynchronously reads a non-strict LEB128 `usize`.",
148        read_uleb_usize_non_strict_async,
149        usize,
150        NonStrict
151    );
152    leb128_read_method!(
153        "Asynchronously reads a strict LEB128 `usize`.",
154        read_uleb_usize_strict_async,
155        usize,
156        Strict
157    );
158    leb128_read_method!(
159        "Asynchronously reads a non-strict LEB128 `i8`.",
160        read_sleb_i8_non_strict_async,
161        i8,
162        NonStrict
163    );
164    leb128_read_method!(
165        "Asynchronously reads a strict LEB128 `i8`.",
166        read_sleb_i8_strict_async,
167        i8,
168        Strict
169    );
170    leb128_read_method!(
171        "Asynchronously reads a non-strict LEB128 `i16`.",
172        read_sleb_i16_non_strict_async,
173        i16,
174        NonStrict
175    );
176    leb128_read_method!(
177        "Asynchronously reads a strict LEB128 `i16`.",
178        read_sleb_i16_strict_async,
179        i16,
180        Strict
181    );
182    leb128_read_method!(
183        "Asynchronously reads a non-strict LEB128 `i32`.",
184        read_sleb_i32_non_strict_async,
185        i32,
186        NonStrict
187    );
188    leb128_read_method!(
189        "Asynchronously reads a strict LEB128 `i32`.",
190        read_sleb_i32_strict_async,
191        i32,
192        Strict
193    );
194    leb128_read_method!(
195        "Asynchronously reads a non-strict LEB128 `i64`.",
196        read_sleb_i64_non_strict_async,
197        i64,
198        NonStrict
199    );
200    leb128_read_method!(
201        "Asynchronously reads a strict LEB128 `i64`.",
202        read_sleb_i64_strict_async,
203        i64,
204        Strict
205    );
206    leb128_read_method!(
207        "Asynchronously reads a non-strict LEB128 `i128`.",
208        read_sleb_i128_non_strict_async,
209        i128,
210        NonStrict
211    );
212    leb128_read_method!(
213        "Asynchronously reads a strict LEB128 `i128`.",
214        read_sleb_i128_strict_async,
215        i128,
216        Strict
217    );
218    leb128_read_method!(
219        "Asynchronously reads a non-strict LEB128 `isize`.",
220        read_sleb_isize_non_strict_async,
221        isize,
222        NonStrict
223    );
224    leb128_read_method!(
225        "Asynchronously reads a strict LEB128 `isize`.",
226        read_sleb_isize_strict_async,
227        isize,
228        Strict
229    );
230}
231
232impl<R> AsyncLeb128ReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}