Added support for negative nthreads and resp. documentation.

[virtualritz]

Description

This makes nthreads accept negative numbers to mean m_pool->size() + nthreads. I.e. on a 16 core machine specifying nthreads as -2 would make OIIO use 14 cores.
If m_pool->size() < -nthreads the result is clamped at 1. I.e. a single thread would be used.

On that note: the original resolve() does not have a check for the case where m_maxthreads > m_pool->size() and should possibly be clamped to the latter, if so. I kept it that way. Is that intended/a feature or an oversight?

Tests

Checklist:

• I have read the contribution guidelines.
• I have updated the documentation, if applicable.
• I have ensured that the change is tested somewhere in the testsuite
  (adding new test cases if necessary).
• If I added or modified a C++ API call, I have also amended the
  corresponding Python bindings (and if altering ImageBufAlgo functions, also
  exposed the new functionality as oiiotool options).
• My code follows the prevailing code style of this project. If I haven't
  already run clang-format before submitting, I definitely will look at the CI
  test that runs clang-format and fix anything that it highlights as being
  nonconforming.

[ssh4net]

Why this can be better than

std::thread::hardware_concurrency() - 2
?

[lgritz]

Can you please remove all spurious formatting changes that are not directly related to the PR? Thanks.

[virtualritz]

Yeah, sorry about that. It seems removing trailing white space on save is a default feature in modern IDEs.
I'll get to it sometime next week.
That said: wouldn't it make sense to remove trailing white space in the entire code base to save anyone from going though this on a PR?
I guess I'm asking if you'd consider a separate PR for just that?

[lgritz]

Yes, certainly. I just want code changes to not have formatting changes to any code that's not changing. A PR that is nothing but formatting changes is fine as long as no code changes. (Among other things, that allows us to add the formatting-only commit hashes to .git-blame-ignore-revs so that they don't change the apparent history or authorship of any actual code.)

[lgritz]

Why this can be better than

std::thread::hardware_concurrency() - 2 ?

1. Because it means 2 less than the pool size, not the HW threading size.
2. Because it can get passed from all sorts of places where it's not convenient to call C++ std::thread_hardware_concurrency(). Like Python? Or from command line args?

[lgritz]

Just to clarify, because I myself was not sure: Does -2 mean "num_hardware_cores - 2" or does it mean "thread_pool_size - 2"?

[lgritz]

This seems to do "pool_size - n"

[lgritz]

I think that your changes only alter the meaning of the nthreads parameter to IBA functions. It is worth noting that there are a few other places where number of threads are passed:

• The setting of the thread pool size with OIIO::attribute("threads", n)
• ImageInput/ImageOutput::threads()
• ImageBuf::threads()
• Utility functions such as parallel_convert_image()
• The paropt structure used by parallel loops and such in parallel.h

Do we want to change those also? If we don't, will this create confusion?

Do those other places misbehave if passed negative thread counts? That's something we may never have considered before because... why would anybody do that? But now, we're giving people a reason to pass negative thread counts, at least in some places, which means we should expect people to do it inadvertently it in any of the other places.