|
1 |
| -A rope-like non-contiguous buffer for efficient data structure serialization |
2 |
| -and vectored output. |
| 1 | +# Chunked Bytes |
| 2 | + |
| 3 | +This crate provides two variants of `ChunkedBytes`, a non-contiguous buffer |
| 4 | +for efficient data structure serialization and vectored output. |
| 5 | + |
| 6 | +In network programming, there is often a need to serialize data structures |
| 7 | +into a wire protocol representation and send the resulting sequence of bytes |
| 8 | +to an output object, such as a socket. For a variety of reasons, developers |
| 9 | +of protocol implementations prefer to serialize the data into |
| 10 | +an intermediate buffer in memory rather than deal with output objects directly |
| 11 | +in either synchronous or asynchronous form, or both. When a contiguous |
| 12 | +buffer like `Vec` is used for this, reallocations to fit a larger length of |
| 13 | +serialized data may adversely impact performance, while evaluating the required |
| 14 | +length to pre-allocate beforehand may be cumbersome or difficult in the |
| 15 | +context. The single contiguous buffer also forms a boundary for write requests, |
| 16 | +creating a need for copy-back schemes to avoid inefficiently fragmented writes |
| 17 | +of tail data. |
| 18 | + |
| 19 | +Another important use case is passing network data through. If some of the data |
| 20 | +is received into [`Bytes`](https://docs.rs/bytes) handles, it should be possible |
| 21 | +to inject the data into the output stream without extra copying. |
| 22 | + |
| 23 | +Enter `ChunkedBytes`, containers that can be used to coalesce data added as |
| 24 | +byte slices via the `BufMut` interface, as well as possible `Bytes` input, |
| 25 | +into a sequence of chunks suitable for implementations of the |
| 26 | +[`Write::write_vectored`][write_vectored] method. This design aims to deliver |
| 27 | +good performance regardless of the size of buffered data and with no need |
| 28 | +to pre-allocate sufficient capacity for it. |
| 29 | + |
| 30 | +[write_vectored]: https://doc.rust-lang.org/stable/std/io/trait.Write.html#method.write_vectored |
3 | 31 |
|
4 | 32 | ## License
|
5 | 33 |
|
|
0 commit comments