Dotnet-api-docs: Effect of setting MaxMessagesPerTask is not clear

[martinmeeser]

I wrote some small tests but I can not see any effect on the outcome.
?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 1a5c9b65-3412-f6aa-e86d-6553bdccf126
• Version Independent ID: 80fd81fd-852b-323b-acc1-a540ca9139ed
• Content: DataflowBlockOptions.MaxMessagesPerTask Property (System.Threading.Tasks.Dataflow)
• Content Source: xml/System.Threading.Tasks.Dataflow/DataflowBlockOptions.xml
• Product: dotnet-api
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[svick]

It's most visible if you also use a task scheduler with limited degree of parallelism. For example, consider this code:

```c#
var exclusiveScheduler = new ConcurrentExclusiveSchedulerPair().ExclusiveScheduler;

var options = new ExecutionDataflowBlockOptions
{
TaskScheduler = exclusiveScheduler,
MaxMessagesPerTask = 1
};

var blockA = new ActionBlock(i => Console.WriteLine($"A {i}"), options);
var blockB = new ActionBlock(i => Console.WriteLine($"B {i}"), options);

for (int i = 0; i < 5; i++)
{
blockA.Post(i);
blockB.Post(i);
}

blockA.Complete();
blockB.Complete();

Task.WaitAll(blockA.Completion, blockB.Completion);

If you run it, you'll see that processing of the two blocks is interleaved, because each `Task` scheduled to the task scheduler will process only one message:

A 0
B 0
A 1
B 1
A 2
B 2
A 3
B 3
A 4
B 4

But if you set `MaxMessagesPerTask` to -1 (the default), one block will process all its messages first, before the second one has any chance to run:

A 0
A 1
A 2
A 3
A 4
B 0
B 1
B 2
B 3
B 4
```

I believe this property is most useful when tweaking performance: more messages per task leads to better throughput, while less messages per task can lead to better latency.

I think the documentation should be expanded here, but I'm not sure a full example (like the one I just showed) is necessary.

[vslee]

I think the documentation should be expanded here, but I'm not sure a full example (like the one I just showed) is necessary.

Your example was helpful, and given the very sparse documentation, I think it would be worthwhile for you to send a PR with your example as an addition.

[lust4life]

https://docs.microsoft.com/en-us/dotnet/standard/parallel-programming/dataflow-task-parallel-library#specifying-the-number-of-messages-per-task

https://stackoverflow.com/a/37836388/3202363

may offer some help.