From 37cbf376eb223b28315bde4d58dbeb90c5309913 Mon Sep 17 00:00:00 2001
From: Ma Shimiao <mashimiao.fnst@cn.fujitsu.com>
Date: Wed, 8 Apr 2015 16:58:59 +0800
Subject: [PATCH] add cpu.cfs_period_us support

Signed-off-by: Ma Shimiao <mashimiao.fnst@cn.fujitsu.com>
Upstream-commit: edbbcc6dae92bc194fe08ec2866ddc8eaac5913d
Component: cli
---
 components/cli/contrib/completion/bash/docker     |  1 +
 .../cli/docs/sources/reference/commandline/cli.md |  2 ++
 components/cli/docs/sources/reference/run.md      | 15 +++++++++++++++
 3 files changed, 18 insertions(+)

diff --git a/components/cli/contrib/completion/bash/docker b/components/cli/contrib/completion/bash/docker
index bb2b4fe8a4..325e50c000 100755
--- a/components/cli/contrib/completion/bash/docker
+++ b/components/cli/contrib/completion/bash/docker
@@ -778,6 +778,7 @@ _docker_run() {
 		--cidfile
 		--cpuset
 		--cpu-shares -c
+		--cpu-period
 		--cpu-quota
 		--device
 		--dns
diff --git a/components/cli/docs/sources/reference/commandline/cli.md b/components/cli/docs/sources/reference/commandline/cli.md
index 1efc528b09..30e2f80d0b 100644
--- a/components/cli/docs/sources/reference/commandline/cli.md
+++ b/components/cli/docs/sources/reference/commandline/cli.md
@@ -950,6 +950,7 @@ Creates a new container.
       --cidfile=""               Write the container ID to the file
       --cpuset-cpus=""           CPUs in which to allow execution (0-3, 0,1)
       --cpuset-mems=""           Memory nodes (MEMs) in which to allow execution (0-3, 0,1)
+      --cpu-period=0             Limit the CPU CFS (Completely Fair Scheduler) period
       --cpu-quota=0              Limit the CPU CFS (Completely Fair Scheduler) quota
       --device=[]                Add a host device to the container
       --dns=[]                   Set custom DNS servers
@@ -1907,6 +1908,7 @@ To remove an image using its digest:
       --cidfile=""               Write the container ID to the file
       --cpuset-cpus=""           CPUs in which to allow execution (0-3, 0,1)
       --cpuset-mems=""           Memory nodes (MEMs) in which to allow execution (0-3, 0,1)
+      --cpu-period=0             Limit the CPU CFS (Completely Fair Scheduler) period
       --cpu-quota=0              Limit the CPU CFS (Completely Fair Scheduler) quota
       -d, --detach=false         Run container in background and print container ID
       --device=[]                Add a host device to the container
diff --git a/components/cli/docs/sources/reference/run.md b/components/cli/docs/sources/reference/run.md
index ff6cfa80ba..93ca0d07f5 100644
--- a/components/cli/docs/sources/reference/run.md
+++ b/components/cli/docs/sources/reference/run.md
@@ -483,6 +483,7 @@ container:
     -m, --memory="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
     -memory-swap="": Total memory limit (memory + swap, format: <number><optional unit>, where unit = b, k, m or g)
     -c, --cpu-shares=0: CPU shares (relative weight)
+    --cpu-period=0: Limit the CPU CFS (Completely Fair Scheduler) period
     --cpuset-cpus="": CPUs in which to allow execution (0-3, 0,1)
     --cpuset-mems="": Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
     --cpu-quota=0: Limit the CPU CFS (Completely Fair Scheduler) quota
@@ -620,6 +621,20 @@ division of CPU shares:
     101    {C1}		1	100% of CPU1
     102    {C1}		2	100% of CPU2
 
+### CPU period constraint
+
+The default CPU CFS (Completely Fair Scheduler) period is 100ms. We can use
+`--cpu-period` to set the period of CPUs to limit the container's CPU usage. 
+And usually `--cpu-period` should work with `--cpu-quota`.
+
+Examples:
+
+    $ docker run -ti --cpu-period=50000 --cpu-quota=25000 ubuntu:14.04 /bin/bash
+
+If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms.
+
+For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt).
+
 ### Cpuset constraint
 
 We can set cpus in which to allow execution for containers.