This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [RFC] [BZ 14417] Document condvar synchronization


On Fri, 2012-09-21 at 12:21 -0600, Jeff Law wrote:
> On 09/21/2012 12:03 PM, Jakub Jelinek wrote:
> > On Fri, Sep 21, 2012 at 02:34:46PM +0200, Torvald Riegel wrote:
> >>      Add explanation of condvar synchronization.
> >
> > I believe documentation for how condvars work should be in
> > nptl/DESIGN-condvar.txt (which exists, but is slightly out of date).

Putting it in DESIGN-condvar.txt is fine with me if everyone prefers
that.  However, I think it's better to put it closer to the source; that
way, it's less easy to forget updating it.

> It's just pseudo code with no real documentation as to how it's supposed 
> to work.

I agree.  What we would ideally want to have documented is why it's
supposed to work: why we need certain checks, and why we don't need
others; why the code is correct wrt. the specification; pointing out
which parts are atomic wrt. each other can help too.

Example executions can help explain the behavior, so I believe we want
those too even if they might increase the amount of documentation
somewhat.  But this is concurrent not sequential code, so there is state
space explosion (i.e., interleavings) and which executions are possible
can quickly become nonobvious (at least to my brain).


Torvald


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]