v3 release

[mroth]

v3 is a breaking change release that migrates to math/rand/v2 and requires Go 1.22 or greater.

Changes from v2

Breaking Changes

1. Module path: github.com/mroth/weightedrand/v3
2. Go version: Requires Go 1.22+ (for math/rand/v2)
3. Removed PickSource: Replaced by PickWith (same functionality using math/rand/v2 source)

Non-Breaking Changes

1. Internal backing changed to uint64: Allows larger weight sums (addresses Use of int for internal counter #31)
2. Uses slices.BinarySearch: Replaces manual searchInts implementation

Implementation Tasks

Code Changes

• Update module path to v3 in go.mod
• Update Go version requirement to 1.22 in go.mod
• Migrate imports from math/rand to math/rand/v2
• Change internal backing from int to uint64
• Remove deprecated PickSource method
• Replace sort.Slice with slices.SortFunc
• Replace manual searchInts with slices.BinarySearch
• Remove historic example programs
• Add PickWith(r *rand.Rand) method for explicit custom rand source
• Simplify Pick() to always use global rand (no conditional)

Tests & Benchmarks

• Add basic tests for PickWith to verify functionality.
• Comparative benchmarks between v2 and v3

Documentation & Release

• Update README: change import path from v2 to v3
• Update README: change Requirements section (Go 1.22+, link to v2 for older versions)
• Update README: pkg.go.dev badge URL to v3

Release Sequence

1. Create v2 branch from main (preserves v2 for maintenance)
2. Comment on related issues explaining how v3 addresses them:
   • Nit: undeprecate PickSource #29: PickWith provides non-deprecated custom rand source support
   • Use of int for internal counter #31: Internal backing changed to uint64 for larger weight sums
   • Feature: Utilize math/rand/v2 #37: Now uses math/rand/v2 with performance improvements
3. Merge PR v3 release #36 to main (use "Closes Nit: undeprecate PickSource #29, Use of int for internal counter #31, Feature: Utilize math/rand/v2 #37" in merge commit)
4. Tag release v3.0.0

Benchmark Comparison (v2 vs v3)

Benchmarks run on Apple M4 Pro, Go 1.24, 10 iterations per benchmark.

Results

                               │ v2 (main)  │              v3 (v3-dev)               │
                               │   sec/op   │    sec/op     vs base                  │
NewChooser/size=1e1-14           98.49n ± 1%   66.09n ± 29%  -32.90% (p=0.000 n=10)
NewChooser/size=1e2-14           405.3n ± 1%   342.6n ±  2%  -15.48% (p=0.000 n=10)
NewChooser/size=1e3-14           3.088µ ± 0%   2.707µ ±  1%  -12.34% (p=0.000 n=10)
NewChooser/size=1e4-14           28.94µ ± 0%   25.01µ ±  2%  -13.58% (p=0.000 n=10)
NewChooser/size=1e5-14           262.6µ ± 1%   243.9µ ±  2%   -7.14% (p=0.000 n=10)
NewChooser/size=1e6-14           2.405m ± 1%   2.291m ±  3%   -4.74% (p=0.000 n=10)
NewChooser/size=1e7-14           28.97m ± 3%   27.25m ±  5%   -5.94% (p=0.000 n=10)
Pick/size=1e1-14                 18.82n ± 7%   18.47n ±  5%        ~ (p=0.353 n=10)
Pick/size=1e2-14                 30.18n ± 0%   29.41n ±  1%   -2.57% (p=0.000 n=10)
Pick/size=1e3-14                 42.22n ± 0%   40.66n ±  0%   -3.68% (p=0.000 n=10)
Pick/size=1e4-14                 54.96n ± 0%   52.76n ±  0%   -4.02% (p=0.000 n=10)
Pick/size=1e5-14                 81.44n ± 0%   77.58n ±  0%   -4.74% (p=0.000 n=10)
Pick/size=1e6-14                 127.0n ± 0%   108.3n ±  1%  -14.72% (p=0.000 n=10)
Pick/size=1e7-14                 251.2n ±15%   231.5n ±  1%   -7.86% (p=0.000 n=10)
PickParallel/size=1e1-14         1.793n ± 7%   1.690n ±  4%   -5.80% (p=0.015 n=10)
PickParallel/size=1e2-14         2.808n ± 2%   2.672n ±  1%   -4.86% (p=0.000 n=10)
PickParallel/size=1e3-14         3.712n ± 2%   3.710n ±  2%        ~ (p=0.868 n=10)
PickParallel/size=1e4-14         4.743n ± 0%   4.789n ±  1%   +0.98% (p=0.000 n=10)
PickParallel/size=1e5-14         6.854n ± 1%   7.064n ±  2%   +3.06% (p=0.000 n=10)
PickParallel/size=1e6-14         10.05n ± 2%   10.71n ±  1%   +6.56% (p=0.000 n=10)
PickParallel/size=1e7-14         22.86n ± 1%   22.68n ±  1%        ~ (p=0.171 n=10)

[trungdlp-wolffun]

I'm very excited to improve. Can I help you, @mroth?

[mroth]

I'm very excited to improve. Can I help you, @mroth?

That'd be great! Now that Go 1.23 is released, mostly what remains here is validating the new method for setting a custom randomness source, seen in cd42f24. I'm still not sure about the API here.

[robinjoseph08]

As a user of v2, I think the API looks good here. As a bonus, it would be nice to rename your NewChooser function to NewChooserWithRand and then make a new simple NewChooser function that just calls NewChooserWithRand with nil as the passed in rand value. I think most people's use-cases will be wanting to set the rand at instantiation, and while you can do it with

c, _ := weightedrand.NewChooser(...)
c.SetRand(r)

it's more convenient to do it all in a single call.

If you're on the fence about including the SetRand method altogether, I personally don't have a major use for it, though I could see it being useful for testing purposes (i.e. swapping out the rand source for each test so that various cases can be tested). Maybe you can leave it off for the first version of v3 (assuming you add the NewChooserWithRand function), and if you get requests for it, you can easily add it back in? It's harder to deprecate/remove functionality than to add it.

Other than that, it all seems reasonable to me, and I'm excited for when it's released!

[mroth]

As a user of v2, I think the API looks good here.

Thank you for the helpful and thoughtful feedback @robinjoseph08 ! Sorry for the delay in response.

...it would be nice to rename your NewChooser function to NewChooserWithRand and then make a new simple NewChooser function that just calls NewChooserWithRand with nil as the passed in rand value. I think most people's use-cases will be wanting to set the rand at instantiation...

Yeah, I can see that. My worry with the ergonomics is that since NewChooser takes Choices as variadic args (perhaps not the best in retrospect, but I don't know if I should change that at this point), the rand source would have to come first in ordering, and its a bit confusing from an idiomatic perspective to have the "option" come first in the parameter ordering. The alternative would be to have a fairly different signature for NewChooserWithRand entirely, e.g.:

// generic type constraints omitted in examples here to aid in clarity of readability:
func NewChooser(choices ...Choice) (*Chooser, error)
func NewChooserWithRand(choices []Choice, r *rand.Rand) (*Chooser, error)

But this presents other ergonomics issues due to the inconsistency (and I generally do think its better to avoid requiring slice construction in the call site, so end-users to not have to deal with declaring []Choice[T, W]{...} in the callsite.

A third alternative could be to offer a chainable func (c *Chooser) WithRand(r *rand.Rand) *Chooser (or perhaps a WithOptions(opts ...ChooserOption) for future proofing), making this settable at instantiation. This could also be introduced in the future.

If you're on the fence about including the SetRand method altogether, I personally don't have a major use for it, though I could see it being useful for testing purposes (i.e. swapping out the rand source for each test so that various cases can be tested). Maybe you can leave it off for the first version of v3 (assuming you add the NewChooserWithRand function), and if you get requests for it, you can easily add it back in? It's harder to deprecate/remove functionality than to add it.

Good points all. I was hoping to reintroduce some way to do this in v3 (due to requests in #29), but this is currently the design decision that is blocking getting to a release...

[mroth]

After some more thought on the API for custom randomness sources, I've landed on a simpler approach than the SetRand method I had prototyped.

Instead of a setter that adds mutable state to the Chooser, I'm going with a dual-method pattern similar to what oklog/ulid does, and very similar to the deprecated PickSource from v2, except using math/rand/v2 for randomness source:

c.Pick()           // uses global rand (the common case)
c.PickWith(rs)     // uses provided *rand.Rand source

This keeps Chooser stateless/immutable after construction, makes the randomness source explicit at the call site, and avoids any potential for surprising behavior in concurrent code.

For the v2 to v3 migration, users of the deprecated PickSource would just rename to PickWith (and update their rand source construction for math/rand/v2).

I did some research into how other Go libraries handle this pattern (google/uuid, gofrs/uuid, oklog/ulid, gonum/sampleuv) and this felt like the cleanest fit.

Planning to move forward with this approach soon unless anyone has concerns or alternative suggestions.