Skip to main content

qubit_io_binary/ext/
async_leb128_write_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 writes.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec_binary::Leb128Codec;
14use qubit_codec_binary::NonStrict;
15use qubit_io::AsyncOutput;
16
17use crate::util::encode_infallible_unchecked;
18use crate::util::write_all_async;
19
20macro_rules! leb128_write_method {
21    ($doc:literal, $name:ident, $ty:ty) => {
22        #[doc = $doc]
23        #[doc = ""]
24        #[doc = "# Parameters"]
25        #[doc = ""]
26        #[doc = "- `value`: Integer to encode and write."]
27        #[doc = ""]
28        #[doc = "# Returns"]
29        #[doc = ""]
30        #[doc = "Returns a future that completes after the canonical payload \
31                 has been written."]
32        #[doc = ""]
33        #[doc = "# Errors"]
34        #[doc = ""]
35        #[doc = "Returns an output error, including a write-zero error when \
36                 the output stops making progress."]
37        #[doc = ""]
38        #[doc = "# Cancellation safety"]
39        #[doc = ""]
40        #[doc = "This operation is not cancellation safe. Dropping the future \
41                 retains any bytes already written to the output."]
42        #[inline(always)]
43        fn $name(&mut self, value: $ty) -> impl Future<Output = Result<()>> + '_
44        where
45            Self: Unpin,
46        {
47            async move {
48                let mut bytes = [0_u8;
49                    Leb128Codec::<$ty, NonStrict>::MAX_ENCODE_UNITS_PER_VALUE];
50                type Codec = Leb128Codec<$ty, NonStrict>;
51                // SAFETY: The local buffer has the codec's maximum payload
52                // size.
53                let len = unsafe {
54                    encode_infallible_unchecked::<Codec>(value, &mut bytes, 0)
55                };
56                write_all_async(self, &bytes[..len]).await
57            }
58        }
59    };
60}
61
62/// Future-based canonical LEB128 writes to runtime-neutral async outputs.
63///
64/// # Cancellation safety
65///
66/// These writes are not cancellation safe. Dropping a pending future leaves
67/// an already-written prefix in the output.
68pub trait AsyncLeb128WriteExt: AsyncOutput<Item = u8> {
69    leb128_write_method!(
70        "Asynchronously writes LEB128 `u8`.",
71        write_uleb_u8_async,
72        u8
73    );
74    leb128_write_method!(
75        "Asynchronously writes LEB128 `u16`.",
76        write_uleb_u16_async,
77        u16
78    );
79    leb128_write_method!(
80        "Asynchronously writes LEB128 `u32`.",
81        write_uleb_u32_async,
82        u32
83    );
84    leb128_write_method!(
85        "Asynchronously writes LEB128 `u64`.",
86        write_uleb_u64_async,
87        u64
88    );
89    leb128_write_method!(
90        "Asynchronously writes LEB128 `u128`.",
91        write_uleb_u128_async,
92        u128
93    );
94    leb128_write_method!(
95        "Asynchronously writes LEB128 `usize`.",
96        write_uleb_usize_async,
97        usize
98    );
99    leb128_write_method!(
100        "Asynchronously writes LEB128 `i8`.",
101        write_sleb_i8_async,
102        i8
103    );
104    leb128_write_method!(
105        "Asynchronously writes LEB128 `i16`.",
106        write_sleb_i16_async,
107        i16
108    );
109    leb128_write_method!(
110        "Asynchronously writes LEB128 `i32`.",
111        write_sleb_i32_async,
112        i32
113    );
114    leb128_write_method!(
115        "Asynchronously writes LEB128 `i64`.",
116        write_sleb_i64_async,
117        i64
118    );
119    leb128_write_method!(
120        "Asynchronously writes LEB128 `i128`.",
121        write_sleb_i128_async,
122        i128
123    );
124    leb128_write_method!(
125        "Asynchronously writes LEB128 `isize`.",
126        write_sleb_isize_async,
127        isize
128    );
129}
130
131impl<W> AsyncLeb128WriteExt for W where W: AsyncOutput<Item = u8> + ?Sized {}