class VmCompressor

The VmCompressor represents a single instance of a compression operation that can be performed

with a minimal locking protocol between a VMO page owner, and the compressor. There are two

different actors that may access and interact with the compressor:

1. The owner of the VmCompressor instance.

2. The holder of the lock to the VMO that owns the temporary reference from this VmCompressor.

The temporary reference exists to allow for the, hopefully unlikely, scenario where another

thread wants access to the page whilst compression is in progress, and it works as follows:

* With the VMO lock held, a vm_page_t in a page list is replaced with the temporary reference

of the VmCompressor.

At this point the VmCompressor owns the vm_page_t, but the VMO owns the temporary reference. From

here any reference to a VMO or the VMO lock refers to the owner of the temporary reference.

* With the VMO lock *not* held the data in the page is compressed resulting in success or

failure.

During this process the VMO lock was not held, allowing another thread to lookup this page and

find the temporary reference. If the temporary reference is found it can treat it like any other

compressed reference and decompress it. Decompression of the temporary reference does not have

to synchronize on the compression attempt, rather it can just copy page (since the compressor

does not modify it).

Decompression is free to read the page, knowing it cannot be changed, due to holding the VMO

lock. This is because for the original thread to progress after performing the compress step it

must.

* Acquire the VMO lock, see if the temporary reference is still there, and resolve any success

or failure of the compression.

In this case if the temporary reference is still there then it is replaced with the compression

result (either a compress reference if it succeed, or the original page again if it failed).

As we are holding the VMO lock we know that either the temporary reference is there, and we hold

the lock, so no one else can be using it, or the temporary reference is not there and so it must

have been returned, and so no on else can be using it. Therefore the compressor can be reset.

In order to know that the temporary reference is no longer in use we require that it not move

between slots in the page list (or between different page lists). This represents the one time

where a compressed reference must be eagerly decompressed even if the data is not being accessed.

This process of using a temporary reference that can resolve to performing a parallel copy

provides some important properties:

1. Requesting a page blocks either on decompression, or a memcpy, but never compression.

2. Compression is performed on an owned page, and not on a page still in the VmPageList,

ensuring that the compression algorithm does not have to tolerate mutations during

compression.

The VmCompressor also helps to manage the update of metadata associated with the vm_page_t being

compressed. The owner of the VmCompressor provides the current value of this metadata to |Start|

along with the vm_page_t.

The holder of the lock to the VMO that owns the temporary reference may update this metadata at

any time after |Start| is called and prior to |TakeCompressionResult| being called.

Only the lock holder may call |TakeCompressionResult|, so at this time the VmCompressor will

ensure that the final compressed reference points to the updated metadata (when compression

succeeds) or the updated metadata is returned to the caller (when compression fails).

The updated metadata is also returned to the caller when decompressing a page. In both the cases

of compression failure or active decompression, it is the caller's responsibiliy to handle the

updated metadata in whatever way it deems appropriate. The meaning of the metadata is opaque to

the VmCompressor.