decision: add details of mmapstorage
@@ -409,6 +409,40 @@ assert (((struct foo *)keyValue (dup))->x == 0);
assert (((struct foo *)keyValue (dup))->x == 0);
```
+#### Compatibility with `mmapstorage` plugin
+
+If we do change the internal data structures it makes much more sense to fix the cache and mmapstorage afterwards (or in tandem).
+The most important constraint for mmap is that any structure (or bytes) that is an allocation unit (e.g. we malloc() the bytes needed for KeySet struct, so this is an unit) needs to have a flag to determine whether those bytes are actually malloc()ed or they are mmap()ed.
+Thus all the newly added structures as proposed will need some kind of an mmap flag.
+
+`mmapstorage` only calls `munmap` in some error cases, so basically `munmap` is almost never done and the keyset is never invalidated.
+
+During `kdbSet` the storage plugins always write to a temp file, due to how the resolver works.
+We also don't need to mmap the temp file here: when doing `kdbSet` we already have the `KeySet` at hand, mmap-ing it is not needed at all, because we have the data.
+We just want to update the cache file.
+The `mmap`/`munmap` in kdbSet are just so we can write the KeySet to a file in our format.
+(`mmap()` is just simpler, but we could also `malloc()` a region and then `fwrite()` the stuff)
+
+Therefore the only case where we return a `mmap()`ed KeySet should be in `kdbGet`.
+
+When the `mmapstorage` was designed/implemented, not all structures had refcounters, so there was no way to know when a `munmap` is safe.
+This was simply out of scope at that point in time.
+
+If refcounting is now implemented for all structures, we might be able to properly `munmap` in future.
+
+Two ideas to deal with this in conjunction with our reference counting implementation:
+
+If we have `free` function-pointer along side the refcount, `mmapstorage` (and also other plugins with different allocators) could set it to their own implementation.
+To mimic the current behaviour of `mmapstorage` this would point to a no-op function.
+However, we could also improve things and keep track of when all data has been freed and only then call `munmap`.
+
+Another simpler way to avoid the flag, which doesn't really allow for further improvements, would be using the refcount.
+`mmapstorage` could set the refcount to a value that is otherwise illegal.
+This would allow us to detect the keys.
+Depending on the refcount implementation good values would probably be 0 or UINT16_MAX.
+The special value would have to ignored by all refcounting functions (inc, dec, del) and turn the functions into no-ops.
+
+
#### Possible Optimizations
- This approach requires more allocations than previously.
