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

ntex_bytes/
lib.rs
