Document PGO usage

README.md

@@ -91,6 +91,8 @@ assert_eq!(parsed, data);
 
 For now, see [here](https://github.com/FlixCoder/rust_serialization_benchmark/tree/add-brief).
 
+If you are interested in maximum performance, please try using profile-guided optimization. It measurably improves performance on this library. For further information, see the [PGO usage docs](./docs/pgo.md).
+
 ### Results
 
 The serialization/deserialization is reasonably fast. Between postcard and serde_json mostly. The data-size is also between postcard and JSON.

docs/pgo.md

@@ -0,0 +1,39 @@
+# [Profile-Guided Optimization (PGO)](https://en.wikipedia.org/wiki/Profile-guided_optimization)
+
+PGO is a technique to automatically improve a program's runtime performance based on profiling.
+
+PGO should be applied to the final executable, it cannot be applied to the Rust crate, nor is a pre-compiled static library provided. If you want to benefit from PGO for maximum performance, you will need to follow the steps below.
+
+There is various ways to do this, but in general, it follows these steps:
+
+1. Create a set of realistic data/examples/benchmarks. PGO needs to be primed with profiling, using unrealistic data can degrade performance in production, even if performance increases in the test cases.
+2. Compile/build an instrumented executable.
+3. Run instrumentation to collect profile data.
+4. Compile/build the final executable given the profile data with PGO enabled optimizations.
+
+PGO can be time consuming and results vary. Always test the improvements on your use-case to see whether it helps and how much.
+
+## Applying PGO
+
+[Rust provides a guide on the use of PGO](https://doc.rust-lang.org/rustc/profile-guided-optimization.html) and there is a nice tool, [cargo pgo](https://github.com/Kobzol/cargo-pgo), to simplify application of PGO.
+
+Using this tool, building a PGO-optimized executable is as simple as:
+
+```bash
+# Build the instrumented executable.
+cargo pgo instrument build
+# Run the instrumented binary to produce profiles.
+cargo pgo instrument run
+# Build the optimized executable.
+cargo pgo optimize
+```
+
+Instrumentation can also be applied to tests and benchmarks. See the [documentation of cargo pgo](https://github.com/Kobzol/cargo-pgo) for further information.
+
+## Expected Results
+
+[Results on benchmarks of this library](https://github.com/FlixCoder/serde-brief/issues/5) have shown very noticable improvements in performance. There is varying speed-ups, but realisticly I would guess it is about 30% improvements, currently (Version 0.1.0).
+
+## Further Resources
+
+- [Various PGO results & resources](https://github.com/zamazan4ik/awesome-pgo)

src/docs/mod.rs

@@ -1,7 +1,12 @@
 //! Here lives more detailed documentation and explanations for this crate and its binary format.
 //!
 //! - [Format Specification](./format/index.html)
+//! - [Profile-Guided Optimization](./pgo/index.html)
 
 pub mod format {
 	#![doc = include_str!("../../docs/format-specification.md")]
 }
+
+pub mod pgo {
+	#![doc = include_str!("../../docs/pgo.md")]
+}

src/lib.rs

@@ -16,8 +16,8 @@
 //!
 //! ## More Detailed Documentation
 //!
-//! See more detailed documentation in [the docs module](./docs/index.html). It contains information
-//! on the binary representation format.
+//! See more detailed documentation in [the docs module](./docs/index.html). It also contains
+//! information on the binary representation format.
 //!
 //! ## Feature Flags
 //!
@@ -95,6 +95,11 @@
 //! 	byte_vec: Vec<u8>,
 //! }
 //! ```
+//!
+//! ## Performance
+//!
+//! If you are interested in maximum performance, please take a look at the [PGO usage
+//! documentation](./docs/pgo/index.html).
 #![cfg_attr(not(feature = "std"), no_std)]
 
 #[cfg(feature = "alloc")]