Skip to content

Commit 0326f94

Browse files
committed
Fill out the README
Explain why was it all needed to begin with.
1 parent d163663 commit 0326f94

File tree

1 file changed

+30
-2
lines changed

1 file changed

+30
-2
lines changed

README.md

+30-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,33 @@
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
331

432
## License
533

0 commit comments

Comments
 (0)