[concurrency-interest] RE: ReentrantWriterPreferenceReadWriteLock -- Deadlock if reader releases lock more times than it aquires lock

David Holmes dholmes@dltech.com.au
Thu, 5 Dec 2002 09:25:01 +1000

Dimitre Chtilianov wrote:
> My personal criterion for a good library is whether it needs
> code samples in its docs.
> If there are code samples in the docs, that almost allways
> means the library needs specific pattern of use, which means
> it is not good enough. At least not general enough.

I don't think it is that simple. Usage examples are *good*
documentation that are an important part of a good library. Any tool
requires specific patterns of use - the question is whether those
patterns are 'minimal' in the sense that the tool is as easy to use
correctly as is feasible. Now depending on the library those usage
patterns might be trivial - eg a math library should consist to
independent functions whose usage is simple invocation to get a
result. A graphics library is more complex, you have to perform
sequences of actions in the right order to get the desired affect. A
concurrency library is somewhere in between, I think: it's not a
simple as one-off independent invocations because most actions are
paired - lock/unlock, await/signal, acquire/release - but it doesn't
have as complex usage sequences as say graphics libraries because the
interface is narrower.

The documentation has to instruct the user how to use the tool
correctly and, sometimes, how not to use the tool.

Just my 2c.

David Holmes