Add --cpus context

[richlander]

I made a few changes:

• Add --cpus context.
• Add DOTNET_PROCESSOR_COUNT context.
• Fix my broken math!

@Maoni0 @jkotas

[Maoni0]

I view memory limit very different from cpu limit because they are handled very differently. memory limit is heavily influenced by the GC where cpu limit is just enforced by the OS (and specified by something in a container), the only thing GC does there is how many heaps it creates because of different ways to interpret the cpu limit.

memory limit has been supported since .net core 3.0.

it'd be good to talk about the difference between the 2 ways of specifying cpu limits - one is by affinity, ie, the process can only run on these individual cores and the other one is by cpu time limit, ie, the process can run on any cores this container can use, but the total cpu time is limited to a number.

and it would be really helpful to discuss these not just in the low level configs in the runtime, but a mapping between what the customers specify and how the runtime interprets that. so something like

if you specify docker run --rm -m 256mb --cpus 2, it translates to 256*0.75 for the GC heap limit and 2 GC heaps (is it 2 GC heaps or more than 2? in other words, when GC asks the VM side for the # of cores this process can use, would it get 2 or more than 2?).

if you specify ``docker run --rm -m 256mb --cpuset-cpus 2`, it translates to 256*0.75 for the GC heap limit and 2 GC heaps (no ambiguity there)

and if a user wants to do more detailed config, there's also the hardlimit configs and the GCHeapCount config they can use.

[richlander]

I added a bunch more context to address your feedback @Maoni0.

I view memory limit very different from cpu limit because they are handled very differently.

Sure, but they both impact the # of GC heaps. Right?

How many cores with the GC see?

By default, it will match --cpus.

This is how CPU affinity works.

% docker run --rm -it -m 256mb --cpuset-cpus 0,2,3  mcr.microsoft.com/dotnet/samples | grep Processor
ProcessorCount: 3

Here, I'm saying, please use these three specific CPUs. They are then unavailable for other containers. This option is only supported on Linux.

One can imagine "I'd like to lease 3 CPUs but don't care which they are." At least via the docker CLI, that option doesn't exist. It sounds like a cool option to me. However, it has a sort of "fragmentation" problem. From an orchestrator standpoint, you then need to find a pod that can deliver that. With the CPU time idea, it enables over provisioning. Whether that's a good thing is a different question.

[jkotas]

Title in INDEX.md needs to be updated to pass the CI checks

[omajid]

Would it make sense to add an example of what a GCHeapHardLimit hex value looks like? Does it have a prefix like 0xf00d or f00d?

For GCHeapHardLimitPercent, does it range from 0 to 100 (or hex 0x0 to 0x64)?

[jkotas]

We have the full documentation with examples and other details at https://docs.microsoft.com/en-us/dotnet/core/runtime-config/garbage-collector

Should we move some of these edits to the official docs instead?

[omajid]

Thanks! I think just having links to the full docs will be great!

[richlander]

Added the link to the doc.

[richlander]

@Maoni0 -- I ran a bunch of tests in a variety of important scenarios. The tests validate the spec, AFAICT. I even tested the 256mb scenario in the doc. The math worked out as expected.

dotnet/runtime#71413

[richlander]

I think this PR is ready to go now. Are your concerns addressed @Maoni0?