Data.Columbia.Gc

A brief note on the locking strategy:

A Columbia data file is covered by three locks: a dual lock (comprising two locks) and a writer lock; the lock hierarchy goes in that order. The dual lock is taken in a shared mode during all reading. The only circumstance in which the dual lock is taken in exclusive mode is to execute the write phase of a garbage collection.

The writer lock protects the action of writing to the end of the file and also to the root node offset; readers take the writer lock only during reading the root node offset; the writer lock is always taken in exclusive mode.

The high level view is: you can always run the collector in parallel with any other operation you are doing; you can read freely while using the collector; writes to the file will be held up until the collector finishes.

Documentation

markAndSweepGc :: FilePath -> [IORef Word32] -> IO ()

Garbage collection for files. It is a good idea when using garbage collection, never to be holding addresses into a file when releasing that file's lock, as at that point the garbage collector may move the data referenced. There is also a pattern, where only one thread runs the garbage collector; in that case, the collector thread may hold addresses and have these updated when the garbage collector moves data. These are currently the only safe patterns for using addresses with the collector:

• Multi-thread GC with use of addresses protected by locks.
• Single-thread GC with use of addresses unprotected by locks solely in the GC thread and protected use of addresses in other threads.

Also note that appropriate locks are applied automatically when you use the wrappers in Data.Columbia.Utils, but must be applied manually in the same manner when not using those patterns.