ntex_bytes/
lib.rs

1//! Provides abstractions for working with bytes.
2//!
3//! The crate provides immutable [`Bytes`] and mutable [`BytesMut`] buffers,
4//! UTF-8 [`ByteString`] values, paged buffers through [`BytePages`], and the
5//! [`Buf`] and [`BufMut`] traits.
6//!
7//! # `Bytes`
8//!
9//! `Bytes` is an efficient container for storing and operating on contiguous
10//! slices of memory. It is intended for use primarily in networking code, but
11//! could have applications elsewhere as well.
12//!
13//! `Bytes` values facilitate zero-copy network programming by allowing multiple
14//! `Bytes` objects to point to the same underlying memory. This is managed by
15//! using a reference count to track when the memory is no longer needed and can
16//! be freed.
17//!
18//! A common pattern is to write into a [`BytesMut`] and extract immutable
19//! [`Bytes`] views:
20//!
21//! ```rust
22//! use ntex_bytes::{BytesMut, BufMut};
23//!
24//! let mut buf = BytesMut::with_capacity(1024);
25//! buf.put(&b"hello world"[..]);
26//! buf.put_u16(1234);
27//!
28//! let a = buf.take();
29//! assert_eq!(a, b"hello world\x04\xD2"[..]);
30//!
31//! buf.put(&b"goodbye world"[..]);
32//!
33//! let b = buf.take();
34//! assert_eq!(b, b"goodbye world"[..]);
35//!
36//! assert_eq!(buf.capacity(), 998);
37//! ```
38//!
39//! In this example, a single 1,024-byte allocation is reused. The `a` and `b`
40//! handles retain immutable views into that allocation, while `buf` continues
41//! using its remaining capacity.
42//!
43//! See [`Bytes`] and [`BytesMut`] for details about sharing, splitting, and
44//! allocation behavior.
45//!
46//! # Interoperability
47//!
48//! [`Bytes`] and [`BytesMut`] implement the [`Buf`](::bytes::Buf) trait of the
49//! `bytes` crate, and [`BytesMut`] also implements its
50//! [`BufMut`](::bytes::BufMut) trait. [`Bytes`] and [`ByteString`] implement
51//! `serde`'s `Serialize` and `Deserialize`.
52//!
53//! # Crate features
54//!
55//! - `simd` enables SIMD-accelerated UTF-8 validation.
56//! - `overuse` enables diagnostic logging for unusually large page stacks.
57#![doc(html_root_url = "https://docs.rs/ntex-bytes/")]
58#![deny(clippy::pedantic)]
59#![allow(
60    unsafe_op_in_unsafe_fn,
61    clippy::cast_sign_loss,
62    clippy::cast_possible_wrap,
63    clippy::cast_possible_truncation,
64    clippy::must_use_candidate,
65    clippy::unnecessary_wraps
66)]
67
68extern crate alloc;
69
70#[macro_use]
71mod macros;
72
73pub mod buf;
74pub use crate::buf::{Buf, BufMut};
75
76mod bvec;
77mod bytes;
78mod debug;
79mod hex;
80mod pages;
81mod serde;
82mod size;
83mod storage;
84mod string;
85mod stvec;
86
87mod stext;
88mod stext_arc;
89
90pub use crate::bvec::BytesMut;
91pub use crate::bytes::Bytes;
92pub use crate::pages::{BytePage, BytePages};
93pub use crate::size::BytePageSize;
94pub use crate::stext::{StorageExt, StorageExtStr, StorageVTable};
95pub use crate::string::ByteString;
96
97#[doc(hidden)]
98pub use crate::stvec::METADATA_SIZE;
99
100#[doc(hidden)]
101#[deprecated]
102pub type BytesVec = BytesMut;
103
104#[doc(hidden)]
105pub mod info {
106    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
107    pub struct Info {
108        pub id: usize,
109        pub refs: u32,
110        pub kind: Kind,
111        pub capacity: usize,
112    }
113
114    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
115    pub enum Kind {
116        Inline,
117        Static,
118        Vec,
119        StExt,
120    }
121
122    /// Storage backing a [`BytePage`](crate::BytePage).
123    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
124    pub enum PageKind {
125        /// Backed by `Bytes`, cloning shares the data.
126        Bytes,
127        /// Backed by `BytesMut` storage, cloning shares the data.
128        Storage,
129        /// Backed by `Vec<u8>`, cloning or splitting copies the data.
130        Vec,
131    }
132}
133
134/// Sets the maximum number of cached page allocations for every page size
135/// on the current thread.
136///
137/// This setting affects only the thread on which it is called.
138#[deprecated(
139    since = "1.11.0",
140    note = "the cache limit depends on the page size, use `set_page_cache_size()`"
141)]
142pub fn set_pages_cache(size: usize) {
143    self::stvec::set_pages_cache(size);
144}
145
146/// Sets the maximum number of cached page allocations of page size `size` on
147/// the current thread.
148///
149/// By default fewer pages are cached for larger page sizes:
150///
151/// | Page size | 4K  | 8K | 16K | 24K | 32K | 48K | 64K | 128K | 256K |
152/// |-----------|-----|----|-----|-----|-----|-----|-----|------|------|
153/// | Pages     | 128 | 64 | 64  | 32  | 16  | 8   | 16  | 2    | 1    |
154///
155/// Buffers of [`BytePageSize::Unset`] are never cached, the call does nothing
156/// for it.
157///
158/// This setting affects only the thread on which it is called.
159pub fn set_page_cache_size(size: BytePageSize, count: usize) {
160    self::stvec::set_page_cache_size(size, count);
161}
ntex_bytes/lib.rs

ntex_bytes/
lib.rs
