1 use crate::leb128
::{self, max_leb128_len}
;
2 use crate::serialize
::{self, Encoder as _}
;
4 use std
::convert
::TryInto
;
6 use std
::io
::{self, Write}
;
7 use std
::mem
::MaybeUninit
;
11 // -----------------------------------------------------------------------------
13 // -----------------------------------------------------------------------------
15 pub type EncodeResult
= Result
<(), !>;
22 pub fn new(data
: Vec
<u8>) -> Encoder
{
26 pub fn into_inner(self) -> Vec
<u8> {
31 pub fn position(&self) -> usize {
36 macro_rules
! write_leb128
{
37 ($enc
:expr
, $value
:expr
, $int_ty
:ty
, $fun
:ident
) => {{
38 const MAX_ENCODED_LEN
: usize = max_leb128_len
!($int_ty
);
39 let old_len
= $enc
.data
.len();
41 if MAX_ENCODED_LEN
> $enc
.data
.capacity() - old_len
{
42 $enc
.data
.reserve(MAX_ENCODED_LEN
);
45 // SAFETY: The above check and `reserve` ensures that there is enough
46 // room to write the encoded value to the vector's internal buffer.
48 let buf
= &mut *($enc
.data
.as_mut_ptr().add(old_len
)
49 as *mut [MaybeUninit
<u8>; MAX_ENCODED_LEN
]);
50 let encoded
= leb128
::$
fun(buf
, $value
);
51 $enc
.data
.set_len(old_len
+ encoded
.len());
58 /// A byte that [cannot occur in UTF8 sequences][utf8]. Used to mark the end of a string.
59 /// This way we can skip validation and still be relatively sure that deserialization
60 /// did not desynchronize.
62 /// [utf8]: https://en.wikipedia.org/w/index.php?title=UTF-8&oldid=1058865525#Codepage_layout
63 const STR_SENTINEL
: u8 = 0xC1;
65 impl serialize
::Encoder
for Encoder
{
69 fn emit_unit(&mut self) -> EncodeResult
{
74 fn emit_usize(&mut self, v
: usize) -> EncodeResult
{
75 write_leb128
!(self, v
, usize, write_usize_leb128
)
79 fn emit_u128(&mut self, v
: u128
) -> EncodeResult
{
80 write_leb128
!(self, v
, u128
, write_u128_leb128
)
84 fn emit_u64(&mut self, v
: u64) -> EncodeResult
{
85 write_leb128
!(self, v
, u64, write_u64_leb128
)
89 fn emit_u32(&mut self, v
: u32) -> EncodeResult
{
90 write_leb128
!(self, v
, u32, write_u32_leb128
)
94 fn emit_u16(&mut self, v
: u16) -> EncodeResult
{
95 self.data
.extend_from_slice(&v
.to_le_bytes());
100 fn emit_u8(&mut self, v
: u8) -> EncodeResult
{
106 fn emit_isize(&mut self, v
: isize) -> EncodeResult
{
107 write_leb128
!(self, v
, isize, write_isize_leb128
)
111 fn emit_i128(&mut self, v
: i128
) -> EncodeResult
{
112 write_leb128
!(self, v
, i128
, write_i128_leb128
)
116 fn emit_i64(&mut self, v
: i64) -> EncodeResult
{
117 write_leb128
!(self, v
, i64, write_i64_leb128
)
121 fn emit_i32(&mut self, v
: i32) -> EncodeResult
{
122 write_leb128
!(self, v
, i32, write_i32_leb128
)
126 fn emit_i16(&mut self, v
: i16) -> EncodeResult
{
127 self.data
.extend_from_slice(&v
.to_le_bytes());
132 fn emit_i8(&mut self, v
: i8) -> EncodeResult
{
133 self.emit_u8(v
as u8)
137 fn emit_bool(&mut self, v
: bool
) -> EncodeResult
{
138 self.emit_u8(if v { 1 }
else { 0 }
)
142 fn emit_f64(&mut self, v
: f64) -> EncodeResult
{
143 let as_u64
: u64 = v
.to_bits();
144 self.emit_u64(as_u64
)
148 fn emit_f32(&mut self, v
: f32) -> EncodeResult
{
149 let as_u32
: u32 = v
.to_bits();
150 self.emit_u32(as_u32
)
154 fn emit_char(&mut self, v
: char) -> EncodeResult
{
155 self.emit_u32(v
as u32)
159 fn emit_str(&mut self, v
: &str) -> EncodeResult
{
160 self.emit_usize(v
.len())?
;
161 self.emit_raw_bytes(v
.as_bytes())?
;
162 self.emit_u8(STR_SENTINEL
)
166 fn emit_raw_bytes(&mut self, s
: &[u8]) -> EncodeResult
{
167 self.data
.extend_from_slice(s
);
172 pub type FileEncodeResult
= Result
<(), io
::Error
>;
174 // `FileEncoder` encodes data to file via fixed-size buffer.
176 // When encoding large amounts of data to a file, using `FileEncoder` may be
177 // preferred over using `Encoder` to encode to a `Vec`, and then writing the
178 // `Vec` to file, as the latter uses as much memory as there is encoded data,
179 // while the former uses the fixed amount of memory allocated to the buffer.
180 // `FileEncoder` also has the advantage of not needing to reallocate as data
181 // is appended to it, but the disadvantage of requiring more error handling,
182 // which has some runtime overhead.
183 pub struct FileEncoder
{
184 // The input buffer. For adequate performance, we need more control over
185 // buffering than `BufWriter` offers. If `BufWriter` ever offers a raw
186 // buffer access API, we can use it, and remove `buf` and `buffered`.
187 buf
: Box
<[MaybeUninit
<u8>]>,
194 pub fn new
<P
: AsRef
<Path
>>(path
: P
) -> io
::Result
<Self> {
195 const DEFAULT_BUF_SIZE
: usize = 8192;
196 FileEncoder
::with_capacity(path
, DEFAULT_BUF_SIZE
)
199 pub fn with_capacity
<P
: AsRef
<Path
>>(path
: P
, capacity
: usize) -> io
::Result
<Self> {
200 // Require capacity at least as large as the largest LEB128 encoding
201 // here, so that we don't have to check or handle this on every write.
202 assert
!(capacity
>= max_leb128_len());
204 // Require capacity small enough such that some capacity checks can be
205 // done using guaranteed non-overflowing add rather than sub, which
206 // shaves an instruction off those code paths (on x86 at least).
207 assert
!(capacity
<= usize::MAX
- max_leb128_len());
209 let file
= File
::create(path
)?
;
211 Ok(FileEncoder { buf: Box::new_uninit_slice(capacity), buffered: 0, flushed: 0, file }
)
215 pub fn position(&self) -> usize {
216 // Tracking position this way instead of having a `self.position` field
217 // means that we don't have to update the position on every write call.
218 self.flushed
+ self.buffered
221 pub fn flush(&mut self) -> FileEncodeResult
{
222 // This is basically a copy of `BufWriter::flush`. If `BufWriter` ever
223 // offers a raw buffer access API, we can use it, and remove this.
225 /// Helper struct to ensure the buffer is updated after all the writes
226 /// are complete. It tracks the number of written bytes and drains them
227 /// all from the front of the buffer when dropped.
228 struct BufGuard
<'a
> {
229 buffer
: &'a
mut [u8],
230 encoder_buffered
: &'a
mut usize,
231 encoder_flushed
: &'a
mut usize,
235 impl<'a
> BufGuard
<'a
> {
237 buffer
: &'a
mut [u8],
238 encoder_buffered
: &'a
mut usize,
239 encoder_flushed
: &'a
mut usize,
241 assert_eq
!(buffer
.len(), *encoder_buffered
);
242 Self { buffer, encoder_buffered, encoder_flushed, flushed: 0 }
245 /// The unwritten part of the buffer
246 fn remaining(&self) -> &[u8] {
247 &self.buffer
[self.flushed
..]
250 /// Flag some bytes as removed from the front of the buffer
251 fn consume(&mut self, amt
: usize) {
255 /// true if all of the bytes have been written
256 fn done(&self) -> bool
{
257 self.flushed
>= *self.encoder_buffered
261 impl Drop
for BufGuard
<'_
> {
263 if self.flushed
> 0 {
265 *self.encoder_flushed
+= *self.encoder_buffered
;
266 *self.encoder_buffered
= 0;
268 self.buffer
.copy_within(self.flushed
.., 0);
269 *self.encoder_flushed
+= self.flushed
;
270 *self.encoder_buffered
-= self.flushed
;
276 let mut guard
= BufGuard
::new(
277 unsafe { MaybeUninit::slice_assume_init_mut(&mut self.buf[..self.buffered]) }
,
282 while !guard
.done() {
283 match self.file
.write(guard
.remaining()) {
285 return Err(io
::Error
::new(
286 io
::ErrorKind
::WriteZero
,
287 "failed to write the buffered data",
290 Ok(n
) => guard
.consume(n
),
291 Err(ref e
) if e
.kind() == io
::ErrorKind
::Interrupted
=> {}
292 Err(e
) => return Err(e
),
300 fn capacity(&self) -> usize {
305 fn write_one(&mut self, value
: u8) -> FileEncodeResult
{
306 // We ensure this during `FileEncoder` construction.
307 debug_assert
!(self.capacity() >= 1);
309 let mut buffered
= self.buffered
;
311 if std
::intrinsics
::unlikely(buffered
>= self.capacity()) {
316 // SAFETY: The above check and `flush` ensures that there is enough
317 // room to write the input to the buffer.
319 *MaybeUninit
::slice_as_mut_ptr(&mut self.buf
).add(buffered
) = value
;
322 self.buffered
= buffered
+ 1;
328 fn write_all(&mut self, buf
: &[u8]) -> FileEncodeResult
{
329 let capacity
= self.capacity();
330 let buf_len
= buf
.len();
332 if std
::intrinsics
::likely(buf_len
<= capacity
) {
333 let mut buffered
= self.buffered
;
335 if std
::intrinsics
::unlikely(buf_len
> capacity
- buffered
) {
340 // SAFETY: The above check and `flush` ensures that there is enough
341 // room to write the input to the buffer.
343 let src
= buf
.as_ptr();
344 let dst
= MaybeUninit
::slice_as_mut_ptr(&mut self.buf
).add(buffered
);
345 ptr
::copy_nonoverlapping(src
, dst
, buf_len
);
348 self.buffered
= buffered
+ buf_len
;
352 self.write_all_unbuffered(buf
)
356 fn write_all_unbuffered(&mut self, mut buf
: &[u8]) -> FileEncodeResult
{
357 if self.buffered
> 0 {
361 // This is basically a copy of `Write::write_all` but also updates our
362 // `self.flushed`. It's necessary because `Write::write_all` does not
363 // return the number of bytes written when an error is encountered, and
364 // without that, we cannot accurately update `self.flushed` on error.
365 while !buf
.is_empty() {
366 match self.file
.write(buf
) {
368 return Err(io
::Error
::new(
369 io
::ErrorKind
::WriteZero
,
370 "failed to write whole buffer",
377 Err(ref e
) if e
.kind() == io
::ErrorKind
::Interrupted
=> {}
378 Err(e
) => return Err(e
),
386 impl Drop
for FileEncoder
{
388 let _result
= self.flush();
392 macro_rules
! file_encoder_write_leb128
{
393 ($enc
:expr
, $value
:expr
, $int_ty
:ty
, $fun
:ident
) => {{
394 const MAX_ENCODED_LEN
: usize = max_leb128_len
!($int_ty
);
396 // We ensure this during `FileEncoder` construction.
397 debug_assert
!($enc
.capacity() >= MAX_ENCODED_LEN
);
399 let mut buffered
= $enc
.buffered
;
401 // This can't overflow. See assertion in `FileEncoder::with_capacity`.
402 if std
::intrinsics
::unlikely(buffered
+ MAX_ENCODED_LEN
> $enc
.capacity()) {
407 // SAFETY: The above check and flush ensures that there is enough
408 // room to write the encoded value to the buffer.
410 &mut *($enc
.buf
.as_mut_ptr().add(buffered
) as *mut [MaybeUninit
<u8>; MAX_ENCODED_LEN
])
413 let encoded
= leb128
::$
fun(buf
, $value
);
414 $enc
.buffered
= buffered
+ encoded
.len();
420 impl serialize
::Encoder
for FileEncoder
{
421 type Error
= io
::Error
;
424 fn emit_unit(&mut self) -> FileEncodeResult
{
429 fn emit_usize(&mut self, v
: usize) -> FileEncodeResult
{
430 file_encoder_write_leb128
!(self, v
, usize, write_usize_leb128
)
434 fn emit_u128(&mut self, v
: u128
) -> FileEncodeResult
{
435 file_encoder_write_leb128
!(self, v
, u128
, write_u128_leb128
)
439 fn emit_u64(&mut self, v
: u64) -> FileEncodeResult
{
440 file_encoder_write_leb128
!(self, v
, u64, write_u64_leb128
)
444 fn emit_u32(&mut self, v
: u32) -> FileEncodeResult
{
445 file_encoder_write_leb128
!(self, v
, u32, write_u32_leb128
)
449 fn emit_u16(&mut self, v
: u16) -> FileEncodeResult
{
450 self.write_all(&v
.to_le_bytes())
454 fn emit_u8(&mut self, v
: u8) -> FileEncodeResult
{
459 fn emit_isize(&mut self, v
: isize) -> FileEncodeResult
{
460 file_encoder_write_leb128
!(self, v
, isize, write_isize_leb128
)
464 fn emit_i128(&mut self, v
: i128
) -> FileEncodeResult
{
465 file_encoder_write_leb128
!(self, v
, i128
, write_i128_leb128
)
469 fn emit_i64(&mut self, v
: i64) -> FileEncodeResult
{
470 file_encoder_write_leb128
!(self, v
, i64, write_i64_leb128
)
474 fn emit_i32(&mut self, v
: i32) -> FileEncodeResult
{
475 file_encoder_write_leb128
!(self, v
, i32, write_i32_leb128
)
479 fn emit_i16(&mut self, v
: i16) -> FileEncodeResult
{
480 self.write_all(&v
.to_le_bytes())
484 fn emit_i8(&mut self, v
: i8) -> FileEncodeResult
{
485 self.emit_u8(v
as u8)
489 fn emit_bool(&mut self, v
: bool
) -> FileEncodeResult
{
490 self.emit_u8(if v { 1 }
else { 0 }
)
494 fn emit_f64(&mut self, v
: f64) -> FileEncodeResult
{
495 let as_u64
: u64 = v
.to_bits();
496 self.emit_u64(as_u64
)
500 fn emit_f32(&mut self, v
: f32) -> FileEncodeResult
{
501 let as_u32
: u32 = v
.to_bits();
502 self.emit_u32(as_u32
)
506 fn emit_char(&mut self, v
: char) -> FileEncodeResult
{
507 self.emit_u32(v
as u32)
511 fn emit_str(&mut self, v
: &str) -> FileEncodeResult
{
512 self.emit_usize(v
.len())?
;
513 self.emit_raw_bytes(v
.as_bytes())?
;
514 self.emit_u8(STR_SENTINEL
)
518 fn emit_raw_bytes(&mut self, s
: &[u8]) -> FileEncodeResult
{
523 // -----------------------------------------------------------------------------
525 // -----------------------------------------------------------------------------
527 pub struct Decoder
<'a
> {
532 impl<'a
> Decoder
<'a
> {
534 pub fn new(data
: &'a
[u8], position
: usize) -> Decoder
<'a
> {
535 Decoder { data, position }
539 pub fn position(&self) -> usize {
544 pub fn set_position(&mut self, pos
: usize) {
549 pub fn advance(&mut self, bytes
: usize) {
550 self.position
+= bytes
;
554 pub fn read_raw_bytes(&mut self, bytes
: usize) -> &'a
[u8] {
555 let start
= self.position
;
556 self.position
+= bytes
;
557 &self.data
[start
..self.position
]
561 macro_rules
! read_leb128
{
562 ($dec
:expr
, $fun
:ident
) => {{ leb128::$fun($dec.data, &mut $dec.position) }
};
565 impl<'a
> serialize
::Decoder
for Decoder
<'a
> {
567 fn read_unit(&mut self) -> () {
572 fn read_u128(&mut self) -> u128
{
573 read_leb128
!(self, read_u128_leb128
)
577 fn read_u64(&mut self) -> u64 {
578 read_leb128
!(self, read_u64_leb128
)
582 fn read_u32(&mut self) -> u32 {
583 read_leb128
!(self, read_u32_leb128
)
587 fn read_u16(&mut self) -> u16 {
588 let bytes
= [self.data
[self.position
], self.data
[self.position
+ 1]];
589 let value
= u16::from_le_bytes(bytes
);
595 fn read_u8(&mut self) -> u8 {
596 let value
= self.data
[self.position
];
602 fn read_usize(&mut self) -> usize {
603 read_leb128
!(self, read_usize_leb128
)
607 fn read_i128(&mut self) -> i128
{
608 read_leb128
!(self, read_i128_leb128
)
612 fn read_i64(&mut self) -> i64 {
613 read_leb128
!(self, read_i64_leb128
)
617 fn read_i32(&mut self) -> i32 {
618 read_leb128
!(self, read_i32_leb128
)
622 fn read_i16(&mut self) -> i16 {
623 let bytes
= [self.data
[self.position
], self.data
[self.position
+ 1]];
624 let value
= i16::from_le_bytes(bytes
);
630 fn read_i8(&mut self) -> i8 {
631 let value
= self.data
[self.position
];
637 fn read_isize(&mut self) -> isize {
638 read_leb128
!(self, read_isize_leb128
)
642 fn read_bool(&mut self) -> bool
{
643 let value
= self.read_u8();
648 fn read_f64(&mut self) -> f64 {
649 let bits
= self.read_u64();
654 fn read_f32(&mut self) -> f32 {
655 let bits
= self.read_u32();
660 fn read_char(&mut self) -> char {
661 let bits
= self.read_u32();
662 std
::char::from_u32(bits
).unwrap()
666 fn read_str(&mut self) -> Cow
<'_
, str> {
667 let len
= self.read_usize();
668 let sentinel
= self.data
[self.position
+ len
];
669 assert
!(sentinel
== STR_SENTINEL
);
671 std
::str::from_utf8_unchecked(&self.data
[self.position
..self.position
+ len
])
673 self.position
+= len
+ 1;
678 fn read_raw_bytes_into(&mut self, s
: &mut [u8]) {
679 let start
= self.position
;
680 self.position
+= s
.len();
681 s
.copy_from_slice(&self.data
[start
..self.position
]);
685 // Specializations for contiguous byte sequences follow. The default implementations for slices
686 // encode and decode each element individually. This isn't necessary for `u8` slices when using
687 // opaque encoders and decoders, because each `u8` is unchanged by encoding and decoding.
688 // Therefore, we can use more efficient implementations that process the entire sequence at once.
690 // Specialize encoding byte slices. This specialization also applies to encoding `Vec<u8>`s, etc.,
691 // since the default implementations call `encode` on their slices internally.
692 impl serialize
::Encodable
<Encoder
> for [u8] {
693 fn encode(&self, e
: &mut Encoder
) -> EncodeResult
{
694 serialize
::Encoder
::emit_usize(e
, self.len())?
;
695 e
.emit_raw_bytes(self)
699 impl serialize
::Encodable
<FileEncoder
> for [u8] {
700 fn encode(&self, e
: &mut FileEncoder
) -> FileEncodeResult
{
701 serialize
::Encoder
::emit_usize(e
, self.len())?
;
702 e
.emit_raw_bytes(self)
706 // Specialize decoding `Vec<u8>`. This specialization also applies to decoding `Box<[u8]>`s, etc.,
707 // since the default implementations call `decode` to produce a `Vec<u8>` internally.
708 impl<'a
> serialize
::Decodable
<Decoder
<'a
>> for Vec
<u8> {
709 fn decode(d
: &mut Decoder
<'a
>) -> Self {
710 let len
= serialize
::Decoder
::read_usize(d
);
711 d
.read_raw_bytes(len
).to_owned()
715 // An integer that will always encode to 8 bytes.
716 pub struct IntEncodedWithFixedSize(pub u64);
718 impl IntEncodedWithFixedSize
{
719 pub const ENCODED_SIZE
: usize = 8;
722 impl serialize
::Encodable
<Encoder
> for IntEncodedWithFixedSize
{
724 fn encode(&self, e
: &mut Encoder
) -> EncodeResult
{
725 let _start_pos
= e
.position();
726 e
.emit_raw_bytes(&self.0.to_le_bytes())?
;
727 let _end_pos
= e
.position();
728 debug_assert_eq
!((_end_pos
- _start_pos
), IntEncodedWithFixedSize
::ENCODED_SIZE
);
733 impl serialize
::Encodable
<FileEncoder
> for IntEncodedWithFixedSize
{
735 fn encode(&self, e
: &mut FileEncoder
) -> FileEncodeResult
{
736 let _start_pos
= e
.position();
737 e
.emit_raw_bytes(&self.0.to_le_bytes())?
;
738 let _end_pos
= e
.position();
739 debug_assert_eq
!((_end_pos
- _start_pos
), IntEncodedWithFixedSize
::ENCODED_SIZE
);
744 impl<'a
> serialize
::Decodable
<Decoder
<'a
>> for IntEncodedWithFixedSize
{
746 fn decode(decoder
: &mut Decoder
<'a
>) -> IntEncodedWithFixedSize
{
747 let _start_pos
= decoder
.position();
748 let bytes
= decoder
.read_raw_bytes(IntEncodedWithFixedSize
::ENCODED_SIZE
);
749 let _end_pos
= decoder
.position();
750 debug_assert_eq
!((_end_pos
- _start_pos
), IntEncodedWithFixedSize
::ENCODED_SIZE
);
752 let value
= u64::from_le_bytes(bytes
.try_into().unwrap());
753 IntEncodedWithFixedSize(value
)