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:

• [x] I have read the contribution guidelines.
• [x] 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).
• [x] 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]

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]

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.