Misleading remarks about degree of parallelism

[baSSiLL]

Type of issue

Missing information

Description

Hello!

The Remarks section for each overload of Parallel.ForAsync, Parallel.ForEachAsync contains the statement
The operation will execute at most ProcessorCount operations in parallel.
However, this only holds true for those overloads which do not have the ParallelOptions parameter. Specifying a value of ParallelOptions.MaxDegreeOfParallelism greater than Environment.ProcessorCount effectively increases the number of parallel operations above the latter value. I have tested this in a container environment where ProcessorCount evaluates to 1 due to CPU limit.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.parallel.forasync?view=net-10.0#remarks

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading.Tasks/Parallel.xml

Document Version Independent Id

0596429c-8a06-a28d-f52c-85fec83cb223

Platform Id

9a4629c1-9f6b-7314-7720-0a7201335a26

Article author

@dotnet-bot

[tannergooding]

effectively increases the number of parallel operations above the latter value.

Concurrency, parallelism, and asynchrony are all related but distinct terms.

In particular parallelism involves simultaneous execution while concurrency may not. So while you can have an indefinite number of concurrent operations, they can only be spread across the physical cores/threads and so are restricted to a maximum of ProcessorCount parallel operations.

MaxDegreeOfParallelism is then a bit of an incomplete name because it impacts both the degree of concurrency and the degree of parallelism, where the latter is still restricted to ProcessorCount as the maximum.

[baSSiLL]

Provided that for containerized environments Environment.ProcessorCount is defined by CPU limits, it is not strictly related to physical cores available to a process. I believe a process can actually run multiple threads in parallel for short periods of time given it does not exceed the CPU limit set on average. Although I haven't actually checked it.

Anyway, your definition of parallelism is all about CPU-bound workloads. However, when running async operations, I'm not interested in how many threads will actually be used to execute tasks. Because async operations are usually I/O-bound and spend much time waiting. What I'm interested in is to do many I/O in parallel so that the whole workload completes sooner. Specifying MaxDegreeOfParallelism > 1 when ProcessorCount = 1 allows to do so. Multiple I/O tasks execute in parallel (or concurrently if you wish) not in sequence and complete way sooner.

I think the aim of good documentation is to make it easier to use the API effectively. The statement I mention is read as "you won't get more tasks executed in parallel than ProcessorCount". And this is really false when MaxDegreeOfParallelism is greater than the default value.

[tannergooding]

Provided that for containerized environments Environment.ProcessorCount is defined by CPU limits, it is not strictly related to physical cores available to a process. I believe a process can actually run multiple threads in parallel for short periods of time given it does not exceed the CPU limit set on average. Although I haven't actually checked it.

A system reporting 1 core should never actually run on more as it would violate various optimizations and other constraints of a system that believes it is single threaded. Even if the host allows migration of that single thread across a greater number of physical cores, that is still transparent to the running code and must itself perform appropriate synchronization, barriers, etc to ensure it is well formed and fitting the memory model.

Anyway, your definition of parallelism is all about CPU-bound workloads

That is the effective meaning of parallel in most programming ecosystems, yes. The fact that an async operation may involve scheduling on a something outside the CPU which can then be concurrent, which can then be parallel is usually irrelevant.

Multiple I/O tasks execute in parallel (or concurrently if you wish) not in sequence and complete way sooner.

They are guaranteed to execute concurrently, they may or may not be in parallel depending on both external device and CPU capabilities.

The statement I mention is read as "you won't get more tasks executed in parallel than ProcessorCount". And this is really false when MaxDegreeOfParallelism is greater than the default value.

This is how you are reading/interpreting it. That does not mean that is how it is read, many users will take away different interpretations.

It is fine to improve the documentation, no one here is against that. It is only important that intent be clarified and that be taken into account with any PR that is aiming to improve things.