Executors, explain vu cycling in arrival-rate

[MattDodsonEnglish]

Closes #136

[github-actions]

There's a version of the docs published here:

https://mdr-ci.staging.k6.io/docs/refs/pull/1016/merge

It will be deleted automatically in 30 days.

[mstoykov]

Suggested change

	then the value of `{exec.vu.iterationInScenario}` will reach `15` at some points,
	even if k6 never requires that number of VUs to reach the target iteration.
	then the value of `{exec.vu.iterationInScenario}` will reach `15` at some points,
	even if k6 never requires that number of VUs to reach the target iteration *at the same time*.

[mstoykov]

Otherwise I can read this as even if I only had to to 10 iterations (1iter/s for 10s) but got 15 VUs I will still use all 15 VUs ... somehow

[MattDodsonEnglish]

Hmm I'm a little lost at both yours and mine.

Maybe:

even if the executor never requires all 15 VUs to reach the target rate.

WDYT?

[mstoykov]

I mean it is better as rate is the key word. My problem is that somebody who doesn't understand this all that well likely will be just as confused.

IMO it is better to be more explicit in what is that we are trying to say when it is confusing to begin with.

In this case for me the key parts are:

1. k6 will use at most as many VUs at a time to hit the provided rate
2. this VUs will not necessarily be the first N VUs only even if only N or less VU are needed at any given moment.

I am not certain guaranteeing that it will go through all the VUs is a good idea - this is an implementation detail that likely is never necessary to be known.

[MattDodsonEnglish]

If it's still confusing with that sentence, I think it might be easier to communicate visually.

For example, if you allocate 4 vus and the target never requires more than two active, k6 still cycles through all four if the test runs long enough. This is to say that the value of {exec.vu.iterationInScenario} will be 3 and 4 at some iterations.

[MattDodsonEnglish]

Thanks, I think it's much more general and useful with: 79c10d6

I added the part about shared array because I want to avoid any chance of confusion if someone misunderstands the admonition. I still kept in a little miniature section in the allocation explanation since a little redundancy can be effective.