Improve docs around grainsize #724
Conversation
| @@ -42,7 +45,8 @@ The grainsize sets a minimum threshold for parallelization. The | |||
| ``parallel_for`` in the example invokes ``ApplyFoo::operator()`` on | |||
| chunks, possibly of different sizes. Let *chunksize* be the number of | |||
| iterations in a chunk. Using ``simple_partitioner`` guarantees that | |||
| [G/2] <= *chunksize* <= G. | |||
| [G/2] <= *chunksize* <= G (a chunk will be between half to all of the | |||
There was a problem hiding this comment.
@aleksei-fedotov , [G/2] is not always low limit for proportional split, is not it? In some corner case, can the low limit be [G/3]? Or simple_partitioner does not use proportional split?
There was a problem hiding this comment.
Yes, you are right. With proportional division the guarantees for simple_partitioner would be [G/3] <= chunksize <= G. However, simpler_partitioner is too simple to be aware of proportional split. Therefore, the original statement is correct.
| @@ -4,8 +4,11 @@ Controlling Chunking | |||
| ==================== | |||
|
|
|||
|
|
|||
| Chunking is controlled by a *partitioner* and a *grainsize.*\ To gain | |||
| the most control over chunking, you specify both. | |||
| Chunking is the process of dividing up the overall work into individual jobs, | |||
There was a problem hiding this comment.
AFAIR, we do not use job in the documentation, maybe it is better to say chunks or sub-ranges? I would not say tasks/jobs because paritioners can proceed several chunks/ranges inside one task.
There was a problem hiding this comment.
The idea of a task is new to me - and I'm not finding it in the docs (loops section anyway). How do the overall work, tasks, and chunks mix?
| @@ -42,7 +45,8 @@ The grainsize sets a minimum threshold for parallelization. The | |||
| ``parallel_for`` in the example invokes ``ApplyFoo::operator()`` on | |||
| chunks, possibly of different sizes. Let *chunksize* be the number of | |||
| iterations in a chunk. Using ``simple_partitioner`` guarantees that | |||
| [G/2] <= *chunksize* <= G. | |||
| [G/2] <= *chunksize* <= G (a chunk will be between half to all of the | |||
There was a problem hiding this comment.
Yes, you are right. With proportional division the guarantees for simple_partitioner would be [G/3] <= chunksize <= G. However, simpler_partitioner is too simple to be aware of proportional split. Therefore, the original statement is correct.
| @@ -4,8 +4,11 @@ Controlling Chunking | |||
| ==================== | |||
|
|
|||
|
|
|||
| Chunking is controlled by a *partitioner* and a *grainsize.*\ To gain | |||
| the most control over chunking, you specify both. | |||
| Chunking is the process of dividing up the overall work into individual jobs, | |||
There was a problem hiding this comment.
| Chunking is the process of dividing up the overall work into individual jobs, | |
| Chunking is the process of dividing up the overall work into independent sub-ranges. |
There was a problem hiding this comment.
@alexey-katranov is it worth mentioning how many tasks can be used and why?
There was a problem hiding this comment.
The problem with an 'independent sub-range' is that it means nothing to most people out there, and defining it here would complicate the simple beginner paragraph this is intended to be. How about we put jobs in quotes to signify that it's not really a job?
| Chunking is controlled by a *partitioner* and a *grainsize.*\ To gain | ||
| the most control over chunking, you specify both. | ||
| Chunking is the process of dividing up the overall work into individual jobs, | ||
| controlled by a *partitioner* and a *grainsize*. The partitioner controls |
There was a problem hiding this comment.
| controlled by a *partitioner* and a *grainsize*. The partitioner controls | |
| This process is controlled by a *partitioner* and a *grainsize*. | |
| A partitioner controls |
| the most control over chunking, you specify both. | ||
| Chunking is the process of dividing up the overall work into individual jobs, | ||
| controlled by a *partitioner* and a *grainsize*. The partitioner controls | ||
| the kind of heuristic applied to the chunking process, and a grainsize |
There was a problem hiding this comment.
| the kind of heuristic applied to the chunking process, and a grainsize | |
| the kind of heuristic applied to the chunking process. A grainsize |
| Chunking is the process of dividing up the overall work into individual jobs, | ||
| controlled by a *partitioner* and a *grainsize*. The partitioner controls | ||
| the kind of heuristic applied to the chunking process, and a grainsize | ||
| controls how small the chunks of work are allowed to be. To gain the most control |
There was a problem hiding this comment.
| controls how small the chunks of work are allowed to be. To gain the most control | |
| determines how small the chunks of work can be. To gain the maximum control |
| controlled by a *partitioner* and a *grainsize*. The partitioner controls | ||
| the kind of heuristic applied to the chunking process, and a grainsize | ||
| controls how small the chunks of work are allowed to be. To gain the most control | ||
| over chunking, you specify both. |
There was a problem hiding this comment.
| over chunking, you specify both. | |
| over the chunking, specify both. |
|
Hi @vadi2 ! Is there any update regarding this pull request? Do you need help with anything? |
Description
I'm not a threading expert, nor do I have a degree in C++, so this library looks like a great fit for me.
While the docs do a great job of explaining the overhead associated with grain sizes, they never really define what a grain size is to begin with. I applied the knowledge I got from running the library + this SO answer to help improve the docs for future users.
Type of change
Choose one or multiple, leave empty if none of the other choices apply
Add respective label(s) to PR if you have permissions
Other information
This is just my stab at improving the docs, if it can be done better or it gets the concepts horribly wrong, let me know.