Added description for 'docker run' command, -c/--cpu-shares flag

Signed-off-by: Shishir Mahajan <shishir.mahajan@redhat.com>
Upstream-commit: 2597bffe9a6538c2db73e2ce380294547b738e2e
Component: engine

components/engine/docs/sources/reference/run.md

@@ -301,6 +301,19 @@ get 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.
 
+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.
+
 ## Runtime privilege, Linux capabilities, and LXC configuration
 
     --cap-add: Add Linux capabilities