samtools/htsjdk — pull request #94 by ryan-williams (2014-09-04 19:30:25+00:00)
Title: a couple of comment tweaks

The change in `DiskBackedQueue` warrants some explanation:

I think there is an OBO error in the implementation of the switch to read-only mode described [there](https://github.com/samtools/htsjdk/pull/85/files#diff-a90c544939c78b1b7cc395c1fe39c4c7R45) (alternatively, the comment was misleading so I've tried to clarify it).

The queue as-is becomes read-only when the last in-memory record is "read" (provided there exist on-disk elements), not when the first on-disk record is read (where I'm taking "read" to mean e.g. "returned by a call to `poll`", not "read from disk into `headRecord` by the internal implementation of `DiskBackedQueue`").

When the last memory record is "read" (e.g. returned by `poll`), `headRecord` is set to the first on-disk record, which is removed from disk, and `canAdd` is set to `false`.

I've put a test case that demonstrates this (by failing when it arguably shouldn't) [here](https://github.com/ryan-williams/htsjdk/commit/95946f91313da35116d3f72400cdaf74931fe989#diff-364721d8daa5c7e21e24283d753ad8ceR78).

I can imagine this error basically never manifesting based on how this queue is used, so if this behavior wasn't intentional then I figured that clarifying this behavior in the comment might be good enough.