fn: cpus documentation (#682)

docs/definitions.md

@@ -83,6 +83,7 @@ curl -H "Content-Type: application/json" -X POST -d '{
     "image": "fnproject/hello",
     "type": "sync",
     "memory": 128,
+    "cpus": "100m",
     "config": {
         "key": "value",
         "key2": "value2",
@@ -125,6 +126,10 @@ In `async` functions the request will be ended with a `call_id` and the function
 
 `memory` defines the amount of memory (in megabytes) required to run this function.
 
+#### cpus (string)
+
+`cpus` defines the amount of CPU cores (in MilliCPUs or floating-point number) required to run this function. For example, `500m` for 1/2 CPU cores or `0.5` for 1/2 CPU cores.
+
 #### config (object of string values)
 
 `config` is a map of values passed to the route runtime in the form of

docs/function-file.md

@@ -14,6 +14,7 @@ name: fnproject/hello
 version: 0.0.1
 type: sync
 memory: 128
+cpus: 100m
 config:
   key: value
   key2: value2
@@ -56,6 +57,11 @@ Default: `sync`.
 function. If this function exceeds this limit during execution, it is stopped
 and error message is logged. Default: `128`.
 
+`cpus` (optional) is the amount of available CPU cores for this function. For example, `100m` or `0.1`
+will allow the function to consume at most 1/10 of a CPU core on the running machine. It
+expects to be a string in MilliCPUs format ('100m') or floating-point number ('0.5').
+Default: unlimited.
+
 `timeout` (optional) is the maximum time a function will be allowed to run. Default is 30 seconds. 
 
 `headers` (optional) is a set of HTTP headers to be returned in the response of

docs/function-format.md

@@ -77,6 +77,7 @@ following, that may be found in the environment instead:
 * `FN_METHOD`
 * `FN_FORMAT`
 * `FN_MEMORY`
+* `FN_CPUS` (present only if `cpus` is set for the route)
 * `FN_TYPE`
 
 #### Pros/Cons

docs/hot-functions.md

@@ -93,6 +93,7 @@ requests:
 		"path": "/hot",
 		"image": "USERNAME/hchttp",
 		"memory": 64,
+		"cpus": "100m",
 		"type": "sync",
 		"config": null,
 		"format": "http",

docs/operating/routes.md

@@ -3,17 +3,22 @@
 Routes have a many-to-one mapping to an [app](apps.md).
 
 A good practice to get the best performance on your Fn API is define
-the required memory for each function.
+the required memory as well as CPU limits for each function.
 
 ## Route level configuration
 
 When creating a route, you can configure it to tweak its behavior, the possible
-choices are: `memory`, `type` and `config`.
+choices are: `memory`, `cpus`, `type` and `config`.
 
 `memory` is number of usable MiB for this function. If during the execution it
 exceeds this maximum threshold, it will halt and return an error in the logs. It
 expects to be an integer. Default: `128`.
 
+`cpus` is the amount of available CPU cores for this function. For example, `100m` or `0.1`
+will allow the function to consume at most 1/10 of a CPU core on the running machine. It
+expects to be a string in MilliCPUs format ('100m') or floating-point number ('0.5').
+Default: `""` or unset, which is unlimited.
+
 `type` is the type of the function. Either `sync`, in which the client waits
 until the request is successfully completed, or `async`, in which the clients
 dispatches a new request, gets a call ID back and closes the HTTP connection.
@@ -26,14 +31,14 @@ Note: Route level configuration overrides app level configuration.
 
 TODO: link to swagger doc on swaggerhub after it's updated.
 
-## Understanding Fn memory management
+## Understanding Fn memory and CPU management
 
-When Fn starts it registers the total available memory in your system
+When Fn starts it registers the total available memory and CPU cores in your system
 in order to know during its runtime if the system has the required amount of
-free memory to run each function. Every function starts the runner reduces the
-amount of memory used by that function from the available memory register. When
-the function finishes the runner returns the used memory to the available memory
-register.
+free memory and CPU to run each function. Every function starts the runner reduces the
+amount of memory and CPU used by that function from the available memory and CPU register.
+When the function finishes the runner returns the used memory and CPU to the available
+memory and CPU register.
 
 ### Creating function
 
@@ -43,13 +48,14 @@ curl -H "Content-Type: application/json" -X POST -d '{
         "path":"<route name>",
         "image":"<route image>",
         "memory": <memory mb number>,
+        "cpus": "<cpus MilliCPUs or floating-point number>",
         "type": "<route type>",
         "config": {"<unique key>": <value>}
     }
 }' http://localhost:8080/v1/apps/<app name>/routes
 ```
 
-Eg. Creating `/myapp/hello` with required memory as `100mb`, type `sync` and
+Eg. Creating `/myapp/hello` with required memory as `100mb`, cpus as `200m`, type `sync` and
 some container configuration values.
 
 ```
@@ -58,6 +64,7 @@ curl -H "Content-Type: application/json" -X POST -d '{
         "path":"/hello",
         "image":"fnproject/hello",
         "memory": 100,
+        "cpus": "200m",
         "type": "sync",
         "config": {"APPLOG": "stderr"}
     }
@@ -70,19 +77,21 @@ curl -H "Content-Type: application/json" -X POST -d '{
 curl -H "Content-Type: application/json" -X POST -d '{
     "route": {
         "memory": <memory mb number>,
+        "cpus": "<cpus MilliCPUs or floating-point number>",
         "type": "<route type>",
         "config": {"<unique key>": <value>}
     }
 }' http://localhost:8080/v1/apps/<app name>/routes/<route name>
 ```
 
-Eg. Updating `/myapp/hello` required memory as `100mb`, type `async` and changed
+Eg. Updating `/myapp/hello` required memory as `100mb`, cpus as `0.2`, type `async` and changed
 container configuration values.
 
 ```
 curl -H "Content-Type: application/json" -X POST -d '{
     "route": {
         "memory": 100,
+        "cpus": "0.2",
         "type": "async",
         "config": {"APPLOG": "stdout"}
     }

docs/writing.md

@@ -38,6 +38,7 @@ the function's format:
 * `FN_METHOD` - the HTTP method for the request, eg: `GET` or `POST`
 * `FN_FORMAT` - a string representing one of the [function formats](function-format.md), currently either `default` or `http`. Default is `default`.
 * `FN_MEMORY` - a number representing the amount of memory available to the call, in MB
+* `FN_CPUS` - a string representing the amount of CPU available to the call, in MilliCPUs or floating-point number, eg. `100m` or `0.1`. Header is present only if `cpus` is set for the route.
 * `FN_TYPE` - the type for this call, currently 'sync' or 'async'
 
 Dependent upon the function's format, additional variables that change on a