Improve description of data integrity in manual
Merge pull request #2942 from cleishm/data-integrity-docs

Improve description of data integrity in manual
Test case for race with commit updating the cache.

When a transaction commits, it will update nodes in the (object) cache
to add relationships to them that were created by the transaction. It is
however possible that the node was not in cache when the transaction
started its commit process, but was put into the cache by another thread
reading the relationships of that node. If this other thread read the
relationships after the committing transaction had written them to the
store, but before it updated the cache, the reading thread would have
already read the relationships that the committing transaction is about
to add into the cache. If that happens, the committing transaction will
still add these relationships, but now they will be in the cache twice
for that node.
Fix for race with commit updating the cache.

Extends the range of the locks acquired while writing to the store, to a
greater region including the place where we update the cache. Also make
sure we acquire corresponding read locks when attempting to read
relationships into the cache for a node.

This should be deadlock free because reader threads only ever acquire
a lock for one node at a time, and release it immediately after updating
that node. And while the writer thread acquires multiple locks, we only
ever have one writer thread acquiring locks at any given time.