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::{
14    Leb128Codec,
15    NonStrict,
16    Strict,
17};
18use qubit_io::AsyncInput;
19
20use crate::util::read_leb128_payload_async;
21
22macro_rules! read_leb128_value_async {
23    ($reader:expr, $ty:ty, $policy:ty) => {
24        read_leb128_payload_async::<
25            { Leb128Codec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
26            Leb128Codec<$ty, $policy>,
27            _,
28        >($reader)
29        .await
30    };
31}
32
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.
69pub trait AsyncLeb128ReadExt: AsyncInput<Item = u8> {
70    leb128_read_method!(
71        "Asynchronously reads a non-strict LEB128 `u8`.",
72        read_uleb_u8_non_strict_async,
73        u8,
74        NonStrict
75    );
76    leb128_read_method!(
77        "Asynchronously reads a strict LEB128 `u8`.",
78        read_uleb_u8_strict_async,
79        u8,
80        Strict
81    );
82    leb128_read_method!(
83        "Asynchronously reads a non-strict LEB128 `u16`.",
84        read_uleb_u16_non_strict_async,
85        u16,
86        NonStrict
87    );
88    leb128_read_method!(
89        "Asynchronously reads a strict LEB128 `u16`.",
90        read_uleb_u16_strict_async,
91        u16,
92        Strict
93    );
94    leb128_read_method!(
95        "Asynchronously reads a non-strict LEB128 `u32`.",
96        read_uleb_u32_non_strict_async,
97        u32,
98        NonStrict
99    );
100    leb128_read_method!(
101        "Asynchronously reads a strict LEB128 `u32`.",
102        read_uleb_u32_strict_async,
103        u32,
104        Strict
105    );
106    leb128_read_method!(
107        "Asynchronously reads a non-strict LEB128 `u64`.",
108        read_uleb_u64_non_strict_async,
109        u64,
110        NonStrict
111    );
112    leb128_read_method!(
113        "Asynchronously reads a strict LEB128 `u64`.",
114        read_uleb_u64_strict_async,
115        u64,
116        Strict
117    );
118    leb128_read_method!(
119        "Asynchronously reads a non-strict LEB128 `u128`.",
120        read_uleb_u128_non_strict_async,
121        u128,
122        NonStrict
123    );
124    leb128_read_method!(
125        "Asynchronously reads a strict LEB128 `u128`.",
126        read_uleb_u128_strict_async,
127        u128,
128        Strict
129    );
130    leb128_read_method!(
131        "Asynchronously reads a non-strict LEB128 `usize`.",
132        read_uleb_usize_non_strict_async,
133        usize,
134        NonStrict
135    );
136    leb128_read_method!(
137        "Asynchronously reads a strict LEB128 `usize`.",
138        read_uleb_usize_strict_async,
139        usize,
140        Strict
141    );
142    leb128_read_method!(
143        "Asynchronously reads a non-strict LEB128 `i8`.",
144        read_sleb_i8_non_strict_async,
145        i8,
146        NonStrict
147    );
148    leb128_read_method!(
149        "Asynchronously reads a strict LEB128 `i8`.",
150        read_sleb_i8_strict_async,
151        i8,
152        Strict
153    );
154    leb128_read_method!(
155        "Asynchronously reads a non-strict LEB128 `i16`.",
156        read_sleb_i16_non_strict_async,
157        i16,
158        NonStrict
159    );
160    leb128_read_method!(
161        "Asynchronously reads a strict LEB128 `i16`.",
162        read_sleb_i16_strict_async,
163        i16,
164        Strict
165    );
166    leb128_read_method!(
167        "Asynchronously reads a non-strict LEB128 `i32`.",
168        read_sleb_i32_non_strict_async,
169        i32,
170        NonStrict
171    );
172    leb128_read_method!(
173        "Asynchronously reads a strict LEB128 `i32`.",
174        read_sleb_i32_strict_async,
175        i32,
176        Strict
177    );
178    leb128_read_method!(
179        "Asynchronously reads a non-strict LEB128 `i64`.",
180        read_sleb_i64_non_strict_async,
181        i64,
182        NonStrict
183    );
184    leb128_read_method!(
185        "Asynchronously reads a strict LEB128 `i64`.",
186        read_sleb_i64_strict_async,
187        i64,
188        Strict
189    );
190    leb128_read_method!(
191        "Asynchronously reads a non-strict LEB128 `i128`.",
192        read_sleb_i128_non_strict_async,
193        i128,
194        NonStrict
195    );
196    leb128_read_method!(
197        "Asynchronously reads a strict LEB128 `i128`.",
198        read_sleb_i128_strict_async,
199        i128,
200        Strict
201    );
202    leb128_read_method!(
203        "Asynchronously reads a non-strict LEB128 `isize`.",
204        read_sleb_isize_non_strict_async,
205        isize,
206        NonStrict
207    );
208    leb128_read_method!(
209        "Asynchronously reads a strict LEB128 `isize`.",
210        read_sleb_isize_strict_async,
211        isize,
212        Strict
213    );
214}
215
216impl<R> AsyncLeb128ReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}