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 cache;
79mod debug;
80mod hex;
81mod pages;
82mod serde;
83mod size;
84mod storage;
85mod string;
86mod stvec;
87
88mod stext;
89mod stext_arc;
90
91pub use crate::bvec::BytesMut;
92pub use crate::bytes::Bytes;
93pub use crate::cache::{PageCacheMetrics, PageCacheSnapshot, PageCacheStats};
94pub use crate::pages::{BytePage, BytePages};
95pub use crate::size::BytePageSize;
96pub use crate::stext::{StorageExt, StorageExtStr, StorageVTable};
97pub use crate::string::ByteString;
98
99#[doc(hidden)]
100pub use crate::stvec::METADATA_SIZE;
101
102#[doc(hidden)]
103#[deprecated]
104pub type BytesVec = BytesMut;
105
106#[doc(hidden)]
107pub mod info {
108    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
109    pub struct Info {
110        pub id: usize,
111        pub refs: u32,
112        pub kind: Kind,
113        pub capacity: usize,
114    }
115
116    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
117    pub enum Kind {
118        Inline,
119        Static,
120        Vec,
121        StExt,
122    }
123
124    /// Storage backing a [`BytePage`](crate::BytePage).
125    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
126    pub enum PageKind {
127        /// Backed by `Bytes`, cloning shares the data.
128        Bytes,
129        /// Backed by `BytesMut` storage, cloning shares the data.
130        Storage,
131        /// Backed by `Vec<u8>`, cloning or splitting copies the data.
132        Vec,
133    }
134}
135
136/// Sets the maximum number of cached page allocations for every page size
137/// on the current thread.
138///
139/// This setting affects only the thread on which it is called.
140#[deprecated(
141    since = "1.11.0",
142    note = "the cache limit depends on the page size, use `set_page_cache_size()`"
143)]
144pub fn set_pages_cache(size: usize) {
145    self::stvec::set_pages_cache(size);
146}
147
148/// Sets the maximum number of cached page allocations of page size `size` on
149/// the current thread.
150///
151/// By default fewer pages are cached for larger page sizes:
152///
153/// | Page size | 4K  | 8K | 16K | 24K | 32K | 48K | 64K | 128K | 256K |
154/// |-----------|-----|----|-----|-----|-----|-----|-----|------|------|
155/// | Pages     | 128 | 64 | 64  | 32  | 16  | 8   | 16  | 2    | 1    |
156///
157/// Buffers of [`BytePageSize::Unset`] are never cached, the call does nothing
158/// for it.
159///
160/// This setting affects only the thread on which it is called.
161pub fn set_page_cache_size(size: BytePageSize, count: usize) {
162    self::stvec::set_page_cache_size(size, count);
163}
ntex_bytes/lib.rs

ntex_bytes/
lib.rs
