diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
| commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
| tree | f435a8308119effd964b339f76abb83a57c29483 /third_party/rust/bincode/readme.md | |
| parent | Initial commit. (diff) | |
| download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip | |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'third_party/rust/bincode/readme.md')
| -rw-r--r-- | third_party/rust/bincode/readme.md | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/third_party/rust/bincode/readme.md b/third_party/rust/bincode/readme.md new file mode 100644 index 0000000000..e91651220f --- /dev/null +++ b/third_party/rust/bincode/readme.md @@ -0,0 +1,112 @@ +# Bincode
+
+<img align="right" src="./logo.png" />
+
+
+[](https://crates.io/crates/bincode)
+[](https://opensource.org/licenses/MIT)
+[](https://blog.rust-lang.org/2017/06/08/Rust-1.18.html)
+
+A compact encoder / decoder pair that uses a binary zero-fluff encoding scheme.
+The size of the encoded object will be the same or smaller than the size that
+the object takes up in memory in a running Rust program.
+
+In addition to exposing two simple functions
+(one that encodes to `Vec<u8>`, and one that decodes from `&[u8]`),
+binary-encode exposes a Reader/Writer API that makes it work
+perfectly with other stream-based APIs such as Rust files, network streams,
+and the [flate2-rs](https://github.com/alexcrichton/flate2-rs) compression
+library.
+
+## [API Documentation](https://docs.rs/bincode/)
+
+## Bincode in the wild
+
+* [google/tarpc](https://github.com/google/tarpc): Bincode is used to serialize and deserialize networked RPC messages.
+* [servo/webrender](https://github.com/servo/webrender): Bincode records webrender API calls for record/replay-style graphics debugging.
+* [servo/ipc-channel](https://github.com/servo/ipc-channel): IPC-Channel uses Bincode to send structs between processes using a channel-like API.
+
+## Example
+
+```rust
+use serde::{Serialize, Deserialize};
+
+#[derive(Serialize, Deserialize, PartialEq, Debug)]
+struct Entity {
+ x: f32,
+ y: f32,
+}
+
+#[derive(Serialize, Deserialize, PartialEq, Debug)]
+struct World(Vec<Entity>);
+
+fn main() {
+ let world = World(vec![Entity { x: 0.0, y: 4.0 }, Entity { x: 10.0, y: 20.5 }]);
+
+ let encoded: Vec<u8> = bincode::serialize(&world).unwrap();
+
+ // 8 bytes for the length of the vector, 4 bytes per float.
+ assert_eq!(encoded.len(), 8 + 4 * 4);
+
+ let decoded: World = bincode::deserialize(&encoded[..]).unwrap();
+
+ assert_eq!(world, decoded);
+}
+```
+
+## Details
+
+The encoding (and thus decoding) proceeds unsurprisingly -- primitive
+types are encoded according to the underlying `Writer`, tuples and
+structs are encoded by encoding their fields one-by-one, and enums are
+encoded by first writing out the tag representing the variant and
+then the contents.
+
+However, there are some implementation details to be aware of:
+
+* `isize`/`usize` are encoded as `i64`/`u64`, for portability.
+* enums variants are encoded as a `u32` instead of a `usize`.
+ `u32` is enough for all practical uses.
+* `str` is encoded as `(u64, &[u8])`, where the `u64` is the number of
+ bytes contained in the encoded string.
+
+## Specification
+
+Bincode's format will eventually be codified into a specification, along with
+its configuration options and default configuration. In the meantime, here are
+some frequently asked questions regarding use of the crate:
+
+### Is Bincode suitable for storage?
+
+The encoding format is stable across minor revisions, provided the same
+configuration is used. This should ensure that later versions can still read
+data produced by a previous versions of the library if no major version change
+has occured.
+
+Bincode is invariant over byte-order in the default configuration
+(`bincode::options::DefaultOptions`), making an exchange between different
+architectures possible. It is also rather space efficient, as it stores no
+metadata like struct field names in the output format and writes long streams of
+binary data without needing any potentially size-increasing encoding.
+
+As a result, Bincode is suitable for storing data. Be aware that it does not
+implement any sort of data versioning scheme or file headers, as these
+features are outside the scope of this crate.
+
+### Is Bincode suitable for untrusted inputs?
+
+Bincode attempts to protect against hostile data. There is a maximum size
+configuration available (`bincode::config::Bounded`), but not enabled in the
+default configuration. Enabling it causes pre-allocation size to be limited to
+prevent against memory exhaustion attacks.
+
+Deserializing any incoming data will not cause undefined behavior or memory
+issues, assuming that the deserialization code for the struct is safe itself.
+
+Bincode can be used for untrusted inputs in the sense that it will not create a
+security issues in your application, provided the configuration is changed to enable a
+maximum size limit. Malicious inputs will fail upon deserialization.
+
+### What is Bincode's MSRV (minimum supported Rust version)?
+
+Bincode 1.0 maintains support for rust 1.18.0. Any changes to this are considered a breaking change for semver purposes.
\ No newline at end of file |