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