Document a little about how join blocks

[cuviper]

No description provided.

[cuviper]

This is trying to address the misunderstanding noted in #338 (comment).

[ChristopherDavenport]

This makes sense to me. I didn't always follow but this is more clear.

[ChristopherDavenport]

This makes sense to me. I didn't always follow but this is more clear.

[nikomatsakis]

I think we should specify something a bit stronger:

"When the calling thread T is in the thread-pool, it will begin by executing closure A, while advertising closure B for other threads to execute. If no other thread is available to execute closure B, then the calling thread will execute closure B once closure A completes.

"You can rely on the fact that closure A is executed to help balance the work-load between the two closures. For example, imagine you have a queue; you may wish to pop the first item and process that in closure A, then recursively process the rest of the queue in closure B. This way, if another thread comes along, it will do the work of splitting up the queue in parallel with processing the first item. If you instead had closure A split the queue, then your current thread would first eagerly create all parallel work items before doing any actual work, increasing the overall overhead."

[cuviper]

Hmm. I actually don't like that queue example much, because it will incur linear stack usage. I don't think it is a good pattern for us to suggest with join.

[nikomatsakis]

Not the best example, I agree, but I think it's important to specify which will execute immediately and which is available for stealing. Maybe just delete the 2nd paragraph? Anybody who cares enough to be tuning like this will have all the info they need in the 1st paragraph (in that case, we could rewrite it to talk about stealing a bit, too, like "while making closure B available to be stolen"; I was trying to avoid jargon but maybe it's better this way, more precise -- we can always link to wikipedia or something).