Yield/Reacquire docs don't talk about task requirements

[rainersigwald]

The docs for IBuildEngine3.Yield() and .Reacquire() describe how to call them and what happens but aren't very crisp on what burdens choosing to use them imposes on a task. We should extend them to describe:

• After calling Yield(), global process state like environment variables and current working directory can change arbitrarily until Reacquire() returns.
• As a result, if you are going to depend on any of that state, for instance by opening files by relative path rather than calling ITaskItem.GetMetadata("FullPath"), you must do so before calling Yield().
• The common pattern is to figure out what all the long-running work is and start it before yielding.

[KalleOlaviNiemitalo]

Is Yield/Reacquire only a mutual exclusion mechanism, or does Yield also save some process state (such as environment variables, current directory, process priority, or standard I/O) that Reacquire then restores?

Does Reacquire have to be called on the same thread as Yield?

[rainersigwald]

Yield doesn't save environment/cwd, but the MSBuild engine will do so before switching the node to another project context, and we may decide to do so at any time after Yield. When Reacquire returns we guarantee that they are restored.

I don't think we have a thread requirement, but I'm not confident enough to say so in docs 😅.

[KalleOlaviNiemitalo]

When Reacquire returns we guarantee that they are restored.

Is that guarantee in the docs?