Crate iobuf [−] [src]
A contiguous region of bytes, useful for I/O operations.
An Iobuf consists of:
- a buffer
- limits (a subrange of the buffer)
- a window (a subrange of the limits)
All iobuf operations are restricted to operate within the limits. Initially,
the window of an Iobuf is identical to the limits. If you have an &mut to
an Iobuf, you may change the window and limits. If you only have a &, you
may not. Similarly, if you have a RWIobuf, you may modify the data in the
buffer. If you have a ROIobuf, you may not.
The limits can be narrowed, but never widened. The window may be set to
any arbitrary subrange of the limits.
Iobufs are cheap to clone, since the buffers are refcounted. Use this to
construct multiple views into the same data.
To keep the struct small (24 bytes!), the maximum size of an Iobuf is 2 GB. Please let me know if you need more than this. I have never before seen a use case for Iobufs larger than 2 GB, and it gives us a 40% smaller struct compared to supporting INT64_MAX bytes. The improved size allows much better register/cache usage and faster moves, both of which are critical for performance.
Although this library is designed for efficiency, and hence gives you lots
of ways to omit bounds checks, that does not mean it's recommended you do.
They merely provide a way for you to manually bounds check a whole bunch
of data at once (with check_range), and then peek or poke out the data
you want. See the documentation for check_range for an example.
To repeat: Do not omit bounds checks unless you've checked very carefully that they are redundant. This can cause terrifying security issues.
Fun tidbit: Data allocated by Iobuf is guaranteed to be aligned to 16 bytes.
This may be abused to write efficient SIMD data processing code.
Structs
| AROIobuf |
Atomic Read-Only Iobuf |
| AppendBuf |
Append-Only Input Buffer |
| IORingbuf |
A ring buffer implemented with |
| ROIobuf |
Read-Only Iobuf |
| RWIobuf |
Read-Write Iobuf |
| UniqueIobuf |
A unique, immutable Iobuf. |
Enums
| BufSpan |
A span over potentially many Iobufs. This is useful as a "string" type where the contents of the string can come from multiple IObufs, and you want to avoid copying the buffer contents unnecessarily. |
| SpanIter |
An iterator over references to buffers inside a |
| SpanMoveIter |
A moving iterator over buffers inside a |
Traits
| Allocator |
Used to provide custom memory to Iobufs, instead of just using the heap. |
| IntLike |
8-64 bit integer types. Not floating point. |
| Iobuf |
Input/Output Buffer |
Type Definitions
| ByteIter |
An iterator over the bytes in a |