GH-36121: [R] Warn for set_io_thread_count() with num_threads < 2

[paleolimbot]

Rationale for this change

Setting the number of threads in the IO thread pool to 1 causes a hang or crash when using some functions (notably: any Acero exec plan).

What changes are included in this PR?

set_io_thread_count() now warns for num_threads == 1:

library(arrow, warn.conflicts = FALSE)
#> Some features are not enabled in this build of Arrow. Run `arrow_info()` for more information.

# Already errors from C++
set_io_thread_count(0)
#> Error: Invalid: ThreadPool capacity must be > 0
# New warning!
set_io_thread_count(1)
#> Warning: `arrow::set_io_thread_count()` with num_threads < 2 may
#> cause certain operations to hang or crash.
#> ℹ Use num_threads >= 2 to support all operations
# No warning!
set_io_thread_count(2)

^{Created on 2023-06-26 with reprex v2.0.2}

Are these changes tested?

Yes

Are there any user-facing changes?

Yes: some existing code may issue a warning that previously did not. Documentation was added.

• Closes: [R] R hangs when read_csv_arrow after set_io_thread_count(1) #36121

[github-actions]

⚠️ GitHub issue #36121 has been automatically assigned in GitHub to PR creator.

[tdhock]

hi @paleolimbot thanks writing a PR that partially addresses the issue I created.
To fully address that issue, can you please add documentation to (1) clarify the difference between IO threads and CPU threads, and (2) to explain which function should be called to control the CSV reading operation?
For (1) a link to the C++ doc web page https://arrow.apache.org/docs/cpp/threading.html would be very helpful.
Could a link to that page be added on the R man pages for arrow::cpu_count and arrow::io_thread_count?
For (2) I would have expected some mention of how to control number of threads used for CSV reading on the man page for read_csv_arrow, but there is no mention of threads on that man page. Something like "use arrow::set_cpu_count(N_CPUS) to tell arrow to use N_CPUS for reading the CSV file" on that man page would be useful.

[paleolimbot]

I'd like to keep the scope of this particular PR to the immediate concern, which is that somebody might set the number of IO threads to 1, observe a hang/crash, and not know why! I promise to follow up on this in #36324 because you're right: we don't dedicate much space to documenting these options and they can have a rather large impact on performance.

[thisisnic]

Thanks, looks good to me!

[conbench-apache-arrow]

Conbench analyzed the 5 benchmark runs on commit 4a93a37a.

There were 3 benchmark results indicating a performance regression:

• Commit Run on arm64-m6g-linux-compute at 2023-06-27 19:19:23Z

  • params=/ConvertToSparseCOOTensorInt32, source=cpp-micro, suite=arrow-tensor-conversion-benchmark

• Commit Run on arm64-t4g-linux-compute at 2023-06-27 19:17:55Z

  • params=1048576/0, source=cpp-micro, suite=arrow-compute-scalar-if-else-benchmark

• and 1 more (see the report linked below)

The full Conbench report has more details.