Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

math/rand: document whether NewSource always implements Source64 #44488

Closed
dsnet opened this issue Feb 22, 2021 · 5 comments
Closed

math/rand: document whether NewSource always implements Source64 #44488

dsnet opened this issue Feb 22, 2021 · 5 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@dsnet
Copy link
Member

dsnet commented Feb 22, 2021

The concrete type returned by NewSource happens to implement Source64. However, this is not documented in any way. Is this always guaranteed?
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Feb 22, 2021
@ulikunitz
Copy link
Contributor

I looked into the source code of rng.go and since Int63() calls Uint64(), NewSource is always returning a Source64 implementation.

// Int63 returns a non-negative pseudo-random 63-bit integer as an int64.
func (rng *rngSource) Int63() int64 {
	return int64(rng.Uint64() & rngMask)
}

@dsnet
Copy link
Member Author

dsnet commented Feb 22, 2021

I believe the snippet you actually wanted to reference is:

go/src/math/rand/rng.go

Lines 237 to 252 in 87e984a

// Uint64 returns a non-negative pseudo-random 64-bit integer as an uint64.
func (rng *rngSource) Uint64() uint64 {
rng.tap--
if rng.tap < 0 {
rng.tap += rngLen
}
rng.feed--
if rng.feed < 0 {
rng.feed += rngLen
}
x := rng.vec[rng.feed] + rng.vec[rng.tap]
rng.vec[rng.feed] = x
return uint64(x)
}

I'm aware that it current returns something that implements Source64 and has done so for many years. The question is whether this should be a documented guarantee (which I think it should be).

@ianlancetaylor
Copy link
Member

I think we should document it.

@cagedmantis cagedmantis added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Feb 23, 2021
@cagedmantis cagedmantis added this to the Backlog milestone Feb 23, 2021
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/352689 mentions this issue: math/rand: update NewSource document

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/425974 mentions this issue: math/rand: document that Source returned by NewSource implements Source64

@golang golang locked and limited conversation to collaborators Sep 2, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
5 participants
@cagedmantis @ianlancetaylor @dsnet @ulikunitz @gopherbot