Copy-on-write snapshot maps

[abyrd]

Summary

As discussed in realtime cleanup meetings, this PR introduces some custom collection classes for use in snapshots of realtime data. It includes interfaces for mutable and immutable maps from keys to single values and from keys to collections of values (multimaps). These are not extensions or re-implementation of Java collections, they are custom-designed for our use case with very narrow functionality. Creating a mutable copy of an immutable map is done at near zero cost, and updates are accumulated in a smaller map layered on top of the existing immutable map until they become numerous enough to justify rehashing a full copy.

OTP realtime data includes a lot of maps serving as indexes into the transit schedules. So far, these maps have not been subject to the same multi-version snapshot system as the transit schedule data itself. This means the indexes and the data they index could get out of sync, or might appear to be out of sync in one request but aligned in another request. This situation has persisted largely because of the perception that making snapshots of these indexes will involve making full copies of huge maps several times per second, wasting a lot of memory bandwidth and incurring lag in publishing the snapshots for use in routing.

The map implementations here are intended to alleviate these concerns, allowing extremely frequent "copies" of large maps, which only incur costs when things are added to them, and even then incur much smaller costs than a complete copy.

Tests

Some tests of basic functionality and speed are included, but in the form of a main method. These will need to be refactored into proper tests.

Documentation

• Some Javadoc is included in the classes, but the design is likely to evolve as we experiment with using this in realtime snapshots. Javadoc and package documentation will be completed when it's clear the system is stabilizing.

Note: the initial version of this code was written by me, but was first drafted in another project with a permissive (MIT) license. If similar code appears elsewhere, it is likely not derived from OTP, but just shares a common ancestor.