Docker's --memory switch does not work as expected - memory

Question

Preamble
I'm writing a little presentation to list some of the "gotchas" when using Docker, and I've run into one of my own.
While explaining the perils of letting Docker run without memory restrictions I've found it doesn't behave the way I expected.
I created a docker image with a PHP script that will recursively create arrays to use up memory, reporting on how much memory is currently used. The script kills itself at 1gb if no memory restriction is put in place.
You can get the image here: https://hub.docker.com/r/gisleburt/my-memory-hog
You can see the source code here: https://github.com/Gisleburt/my-memory-hog
My expectation was that the following would prevent the script going beyond 128mb of memory.
docker run -it --memory=128m --memory-swap=0 gisleburt/my-memory-hog
However, on OSX (both native, and docker-machine using the virtual box driver), the docker actually the script just before 250mb. On Ubuntu the script reaches 1gb and kills itself.
Weirder still, if we inspect what's happening with docker stats, we can see that the container actually doesn't go over it's memory limit. In fact, running with --memory=4m on Ubuntu, docker stats still says it doesn't use more than the 4mb, even though the script completes at 1gb. On Mac, restricting to 4mb kills the script around the 5-6mb mark.
I assume I'm missing something about the way that memory is allocated, but I can't work out what it is.
Question
Why does the script in the docker container appear to use more memory than the docker container? What is happening with the memory inside and outside of the container?
Version Info
Mac Client:
Client:
Version: 1.12.3
API version: 1.24
Go version: go1.6.3
Git commit: 6b644ec
Built: Thu Oct 27 00:09:21 2016
OS/Arch: darwin/amd64
Experimental: true
Mac Native:
Server:
Version: 1.12.3
API version: 1.24
Go version: go1.6.3
Git commit: 6b644ec
Built: Wed Oct 26 23:26:11 2016
OS/Arch: linux/amd64
Mac Virtual Box Machine:
Server:
Version: 1.12.3
API version: 1.24
Go version: go1.6.3
Git commit: 6b644ec
Built: Thu Oct 27 00:09:21 2016
OS/Arch: linux/amd64
Experimental: true
Ubuntu Client:
Client:
Version: 1.12.3
API version: 1.24
Go version: go1.6.3
Git commit: 6b644ec
Built: Wed Oct 26 22:01:48 2016
OS/Arch: linux/amd64
Ubuntu Engine:
Server:
Version: 1.12.3
API version: 1.24
Go version: go1.6.3
Git commit: 6b644ec
Built: Wed Oct 26 22:01:48 2016
OS/Arch: linux/amd64

Answer 1

With the help of a number of people in our tech department, and in particular one member of our platform operations team, we worked out what's going on, and it is mentioned in the reference guide.
--memory-swap Total memory limit (memory + swap, format: <number>[<unit>]). Number is a positive integer. Unit can be one of b, k, m, or g.
To put is plainly, --memory-swap is the total amount of memory available, both resident, and swap.
In order to get the desired effect, you must run:
docker run -it --memory=128m --memory-swap=128m gisleburt/my-memory-hog
In this example memory = 128mb, and memory + swap = 128mb therefore swap = 0.
It also makes sense that you can not specify a number for --memory-swap that is greater than 0, but less that --memory.
Additionally, while --memory-swap=-1 gives you an "infinite" amount of memory via swap, for some reason, setting --memory-swap=0 seems to make memory and swap the same size, giving you a total amount of memory twice what you were expecting.
You can also turn off swapping using --memory-swappiness=0. Although the swap file might be created, it will not be written to, and therefore will not take up any further disk space than an empty file.
TL;DR:
--memory = RES
--memory-swap = VIRT = RES + SWAP