What does --memory-reservation flag do in practice?

Docs say:

Under this configuration, when the container consumes memory more than 200M and less than 500M, the next system memory reclaim attempts to shrink container memory below 200M.

But what does this actually mean?

Let's say I have a container running Solr, and:
docker run -m 1G --memory-reservation 768M solr

What effect does it have on the Solr process inside the container when it starts using 800M memory? Nothing?

Is it only if/when memory usage subsequently drops below 768M... this flag allows docker to reclaim the memory from the solr container? ...otherwise the container would continue to consume whatever the high-water memory usage was?

How does this relate to swarm scheduling? If swarm always allocates 1G for the container because of -m then is --memory-reservation not useful in this context?

Solution 1:

the memory-reservation option is a wrapper for the cgroup option called memory.soft_limit_in_bytes. You can read the (outdated) manual under the 'Soft limits' section: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt

More info on the reclaim process is here: http://linux-mm.org/PageOutKswapd

From what i can tell, your Solr process can use 800MB and as long as there is no contention from other cgroups then memory won't be reclaimed. It can keep the memory and use up to the hard limit of 1GB. If there is contention then the kernel will attempt to reclaim the memory but as per the doc's soft limits is a best-effort feature.. no guarantees.