Merge pull request #10881 from shishir-a412ed/cpu-shares-manpage

man page description for `-c/--cpu-shares` flag for `docker run` command.

docs/man/docker-run.1.md

@@ -88,6 +88,19 @@ the same proportion of CPU cycles, but you can tell the kernel to give more
 shares of CPU time to one or more containers when you start them via **docker
 run**.
 
+The flag `-c` or `--cpu-shares` with value 0 indicates that the running
+container has access to all 1024 (default) CPU shares. However, this value
+can be modified to run a container with a different priority or different
+proportion of CPU cycles.
+
+E.g., If we start three {C0, C1, C2} containers with default values
+(`-c` OR `--cpu-shares` = 0) and one {C3} with (`-c` or `--cpu-shares`=512)
+then C0, C1, and C2 would have access to 100% CPU shares (1024) and C3 would
+only have access to 50% CPU shares (512). In the context of a time-sliced OS
+with time quantum set as 100 milliseconds, containers C0, C1, and C2 will run
+for full-time quantum, and container C3 will run for half-time quantum i.e 50
+milliseconds.
+
 **--cap-add**=[]
    Add Linux capabilities