Skip to content

Latest commit

 

History

History
37 lines (21 loc) · 4.33 KB

MIGRATION.md

File metadata and controls

37 lines (21 loc) · 4.33 KB
Raw

Migration Notes

This document will keep tabs on migration paths between breaking change versions of turborand.

Migration from 0.5 to 0.6

Version 0.6 introduces a major reworking of the crate, with code reorganised and also exposed more granularly via features. First things to note:

  • All major exports for the crate are now in the prelude module. Top level only exports the new traits for turborand.
  • Rng is now split into Rng and AtomicRng, no more top level generics that required exporting internal traits. State trait is now made private and no longer available to be implemented, as this was an internal implementation detail for WyRand.
  • All previous methods for Rng are now implemented in TurboCore, GenCore, SeededCore and TurboRand traits. These are part of the prelude so as long as they are included, all existing methods will work as expected.
  • Rng is now under a feature flag, wyrand. This is enabled by default however, unless default-features = false is applied on the dependency declaration in Cargo.toml.
  • Yeet the rng!, atomic_rng! macros, as these are no longer needed to manage the generics spam that has since been refactored out. Instead, use ::new(), ::default() or ::with_seed(seed) methods instead.

Migration from 0.6 to 0.7

Version 0.7 hasn't changed much except that the internals module is now fully private (so the State traits and CellState/AtomicState structs are no longer public). They are not accessible from the prelude any more. The removal of these from the public API thus constitutes a breaking change, leading to a new major version.

Also, the serialisation format of ChaChaRng has changed, so 0.7 is not compatible with older serialised structs. The plus side is also a flatter serialised format for ChaChaRng. Also, ChaChaRng is no longer backed by a Vec for caching generated entropy, now preferring to use an aligned array for better random number generation at the slight cost of initialisation/cloning performance and increased struct size. This means that the single heap allocation ChaChaRng needed is now reduced to zero.

Migration from 0.7 to 0.8

Version 0.8 seperates the old Clone behaviour into two: standard Clone which maintains the original state and clones it to the new instance as is (and so both old and new equal to each other), and ForkableCore which mutates the state of the original to fork a new instance with a random state generated from the original. Previous usage of .clone() now should make use of .fork() instead. Cloning now should be used where preserving the state of the original to the cloned instance is required.

Migration from 0.8 to 0.9

Version 0.9 introduces no-std compatibility with more granular features as well as minor changes to weighted_sample.

For no-std compatibility, new feature flags have been created. By default, std feature flag is enabled and with fmt providing Debug implementations. Without default features, turborand will expose only methods and implementations that are compatible with no-std environments. alloc is provided as a feature flag for enabling some methods like sample_multiple, which require at least alloc crate support. Traits like Default and methods like new() are only supported in std environments.

For weighted_sample and weighted_sample_mut, the weight_sampler signature has changed from Fn(&T) -> f64 to Fn((&T, usize)) -> f64. The tuple provides not just a reference to the sampled item, but the index as well. There's also a correction to the weighted_sample and weighted_sample_mut lifetimes which should fix some typing issues.

Other minor changes include some removal of unsafe that are no longer necessary with some internal refactors, as well as sample_iter and sample_multiple_iter methods.

Migration from 0.9 to 0.10

Version 0.10 introduces GenCore::GEN_KIND associated constant, needed to be able to toggle between different algorithms for some methods which have different optimum profiles based on the speed of the PRNG and the algorithm itself. Rng and ChaChaRng now use different shuffling algorithms, with ChaChaRng changing compared to previous releases. The internal implementation of ChaChaRng has also changed, enabling better perf with a more standard ChaCha implementation, though it now has a different output.