Help: Clarify Routine's "inheritance" of clocks, times and RNGs [skip ci] #4326
Conversation
| all threads started within will inherit. | ||
| When a routine is created, it "inherits" its random number generator from the parent thread (link::Classes/Thread#.thisThread#thisThread::). If no particular randSeed is set (the normal case), it will tap the same stream of random number generators used by the parent. | ||
|
|
||
| The parent thread is whichever Routine is in force at the moment of creating a new Routine. If no Routine is evaluating at that moment, then the parent is the sclang process master link::Classes/Thread:: -- that is, the default from which all Routines inherit the random number generator. |
There was a problem hiding this comment.
this last clause is a bit oddly worded -- consider "in other words, by default all Routines inherit their RNGs from the main thread". or just nixing it.
HelpSource/Classes/Routine.schelp
Outdated
| (see link::Classes/Thread#-parent::). | ||
| the Routine. | ||
|
|
||
| Time: Just before code::next:: is called, code::thisThread:: points either to another Routine, or the top-level Thread. During the code::next:: call, this becomes the "parent thread" (see link::Classes/Thread#-parent::). code::next:: then evaluates on the parent's clock, at the parent's logical time. |
There was a problem hiding this comment.
also, 'at the parent's logical time' or 'on the parent's logical time'?
There was a problem hiding this comment.
OK, I'll remove the quotes -- but I don't agree with the characterization as scare quotes. In technical writing, sometimes you have to introduce a phrase with a specific meaning that may not be obvious. It's fairly standard to highlight that in some way, either by emphasis or "quoting." (Or perhaps times have changed and quote marks are always "ironic" now.)
Definitely at a specific time.
I think I took care of all the changes now (hope I didn't miss one).
There was a problem hiding this comment.
"scare quotes" also denote non-standard usage, while all of these usages (as far as i can tell) are consistent with their standard definition
HelpSource/Classes/Routine.schelp
Outdated
| In the SuperCollider application, a Routine can be played using a link::Classes/Clock::, as can any link::Classes/Stream::. | ||
| every time the Routine yields, it should do so with a float, the clock will interpret that, usually | ||
| pausing for that many seconds, and then resume the routine, passing it the clock's current time. | ||
| Schedules the Routine on the given link::Classes/Clock::, at a time specified by code::quant::. At that time, the routine will "awake," setting the clock and time and evaluating the routine. If the routine yields a number, this number of beats will be added to the current time and the routine will be rescheduled. (This behavior is compatible with scheduling a link::Classes/Stream:: or a link::Classes/Function::.) |
There was a problem hiding this comment.
scare quotes unnecessary, parens unnecessary.
'wake up' is more standard terminology. Also would recommend capitalizing Routine throughout this paragraph
| @@ -32,8 +32,11 @@ Array.fill(7, r); | |||
|
|
|||
| subsection::Inheriting Seeds | |||
|
|
|||
| Also it is possible to set the seed of the running thread that | |||
| all threads started within will inherit. | |||
| When a routine is created, it "inherits" its random number generator from the parent thread (link::Classes/Thread#.thisThread#thisThread::). If no particular randSeed is set (the normal case), it will tap the same stream of random number generators used by the parent. | |||
There was a problem hiding this comment.
scare quotes unnecessary; capitalize Routine
There was a problem hiding this comment.
Also, this is still unclear to me -- are the two routines sharing the same seed, or the same RNG object? i.e. if r1 spawns r2 and then each calls rand(), will they receive the same number?
|
|
||
| The parent thread is whichever Routine is in force at the moment of creating a new Routine. If no Routine is evaluating at that moment, then the parent is the sclang process master link::Classes/Thread:: -- that is, the default from which all Routines inherit the random number generator. | ||
|
|
||
| To set the master random seed for the entire application, then, evaluate code::thisThread.randSeed = yourSeed:: outside of the context of any routine, as in the example below. |
| @@ -52,6 +55,32 @@ thisThread.randSeed = 1923; | |||
| Array.fill(7, r.value); | |||
| :: | |||
|
|
|||
| When you set code::randSeed:: on a Routine, it switches to its own random number generator, independent of any other. Subsequently, routines created within the independent-RNG routine will inherit the separate random number generator. | |||
There was a problem hiding this comment.
change first "it" to "Routine" for clarity. second sentence is a bit awkward, consider "Any new Routines created within the context of this Routine will inherit its unique RNG."
Purpose and Motivation
A mailing list discussion revealed that some of the documentation about routines "inheriting" state from the parent thread is unclear, and possibly misleading. This PR attempts to clarify a few points.
Types of changes
To-do list