os/exec: Cmd can only be executed once, but that isn't documented

[AlexFinkel]

Once an exec.Cmd has been Run (e.g. through .Run, .Output or .CombinedOutput) calling one of these run methods again will result in an error.

1. This fact isn't documented.
2. The resulting error messages don't clearly identify what caused the problem.
3. This behaviour probably isn't necessary; for many commands it makes perfectly good sense to run them more than once.

I'm not talking about parallel execution here, this is running, checking the output, then running again.

Example error message from calling CombinedOutput more than once:
"exec: Stdout already set."
http://play.golang.org/p/Aaj3Gbva_S

[cznic]

bytes.Buffer is not reusable, in the general case, without issuing a Reset either. IOW, if a complex thing with private fields is not explicitly stated as reusable, it is not. Documenting that for only one thing, exec.Cmd, is not very consistent. Documenting that for every thing in the sdtlib seems like an overkill.

Same approach is used for documenting concurrent access safety everywhere. Unless marked safe, it is implicitly not concurrent safe.

[alexf101]

@cznic I don't really understand your response. The API documented in os/exec doesn't talk about the fact that it's one use, and the cause of errors seem implementation-specific.

Calling a function multiple times safely is the assumed behaviour of most APIs - I wouldn't expect documentation to clarify that it's safe to call fmt.Println multiple times.

If it helps, try to imagine if you were implementing an alternative implementation of the os/exec module. Would it be clear to you (without looking at the code) whether or not Run should be reusable?

[gopherbot]

CL https://golang.org/cl/9440 mentions this issue.

[bradfitz]

This has been documented. I don't believe there was more to do, but let me know if I'm wrong.