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