Fix the docs for SetBackgroundThreads vs max_background_jobs
- Dominant language
- C++
- Stars
- 32.1k
- Forks
- 6.9k
- Avg merge
- 32m
- Merged PRs (30d)
- 1
Description
> Note: Please use Issues only for bug reports. For questions, discussions, feature requests, etc. post to dev group: https://groups.google.com/forum/#!forum/rocksdb or https://www.facebook.com/groups/rocksdb.dev
### Expected behavior
I want to know how, why and when to use SetBackgroundThreads.
### Actual behavior
I am confused.
### Steps to reproduce the behavior
env.h is vague WRT SetBackgroundThreads ([see here](https://github.com/facebook/rocksdb/blob/f515d9d2032e8aced7d92ec7bdb5aecd8585479a/include/rocksdb/env.h#L562))
Still confused after reading the [wiki page](https://github.com/facebook/rocksdb/wiki/Thread-Pool) and the [tuning guide](https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide#tuning-flushes-and-compactions).
Questions I and others have:
* why are both needed, as in, why isn't max_background_jobs sufficient?
* are there sanity checks? I see people trying things like ...
```
db_opt.env->SetBackgroundThreads(NT, rocksdb::Env::Priority::HIGH);
db_opt.env->SetBackgroundThreads(NT, rocksdb::Env::Priority::LOW);
db_opt.max_background_jobs = NT;
```
Note that the [wiki](https://github.com/facebook/rocksdb/wiki/Thread-Pool) example shows how to use SetBackgroundThreads correctly but the [tuning guide](https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide#tuning-flushes-and-compactions) does not and encourages the mistake seen above where _mistake_ means using the same value (NT above) for LOW and HIGH priority pools.
However, the correct example in the wiki uses max_background_flushes and max_background_compactions which have been deprecated. When someone uses max_background_jobs, how are they supposed to know how that is split between compactions and jobs, because that split [isn't documented](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/options.h#L704) in options.h and you have to find it deep in RocksDB code ([see GetBGJobLimits](https://github.com/facebook/rocksdb/blob/559aaa35771e88cd0f8a64a19f534097709e221f/db/db_impl/db_impl_compaction_flush.cc#L2663)).
Contributor guide
Assessment
This issue has not been assessed yet.