Re: DataObjectLockFree: fix facts in doxygen

On Tue, Dec 11, 2012 at 3:46 PM, Peter Soetens <[email protected]>wrote:

> On Tue, Dec 11, 2012 at 3:06 PM, Sébastien Barthélémy
> <[email protected]> wrote:
> > Hello,
> >
> > if I got it right, DataObjectLockFree advertises more than it actually
> does.
> > See attached patch.
>
> Hmm. Thanks for fixing, the code diverged a lot from the docs. What
> remains undocumented is the importance of max_threads. We should
> document this variable instead of :
>
> +     *
> +     * The internal buffer can get full if too many concurrent reads are
> +     * taking to long. In such a case, the write occurs anyway and late
> +     * readers can get corrupted values.
>
> Which should imo read:
>
> +     *
> +     * The internal buffer will get full if more concurrent threads
> than max_threads
> +     * are accessing this object. In such a case, the read occurs
> anyway and late
> +     * readers can get corrupted values.
>

That is better indeed. Yet not totally accurate: many threads (even more
that max_thread) could start reading at the very same time, thus reading
from the same slot and no corruption would occur.

what about

+     * The internal buffer can get full if too many concurrent reads are
+     * taking too long. In such a case, the write occurs anyway and late
+     * readers will get corrupted values.
+     * Thread safety (uncorrupted writes and reads) is guaranteed as long
+     * as only one write and at most max_threads reads occur
+     * concurrently.

And then also fixup the documentation of the constructor. So for
> clarity, this is a single-write 'max_threads-1' readers
> implementation, and it can't detect itself if the user violates this.
>

I think it is a single-write 'max_threads' readers implementation.
Note that buf_len is max_threads+2

I suppose you were you bitten by these false promises ?
>

Not this time!

Cheers

-- 
Orocos-Dev mailing list
[email protected]
http://lists.mech.kuleuven.be/mailman/listinfo/orocos-dev