DataObjectLockFree: fix facts in doxygen
Sébastien Barthélémy <[email protected]>
| Newsgroups | gmane.science.robotics.orocos.devel |
|---|---|
| Message-ID | <CAPkDDd76uMyPWuG-_Fai46JSQQfsjhtJBtDC1iiGPLz5CfT=6w@mail.gmail.com> |
Hello, if I got it right, DataObjectLockFree advertises more than it actually does. See attached patch. -- Cheers Sébastien -- Orocos-Dev mailing list [email protected] http://lists.mech.kuleuven.be/mailman/listinfo/orocos-dev
0001-DataObjectLockFree-fix-facts-in-doxygen.patch
(application/octet-stream, 3 KB)
From 211f36f10fa03a8630b483afab02ec06803054d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Barth=C3=A9l=C3=A9my?= <[email protected]> Date: Tue, 11 Dec 2012 15:01:10 +0100 Subject: [PATCH] DataObjectLockFree: fix facts in doxygen --- rtt/base/DataObjectLockFree.hpp | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/rtt/base/DataObjectLockFree.hpp b/rtt/base/DataObjectLockFree.hpp index d857255..18b97eb 100644 --- a/rtt/base/DataObjectLockFree.hpp +++ b/rtt/base/DataObjectLockFree.hpp @@ -46,31 +46,32 @@ namespace RTT { namespace base { /** - * @brief This DataObject is a Lock-Free implementation, - * such that reads and writes can happen concurrently without priority - * inversions. + * @brief This DataObject is a Lock-Free implementation, such that + * several reads and a single write can happen concurrently without + * priority inversions. * - * When there are more writes than reads, the last write will - * be returned. The internal buffer can get full if too many - * concurrent reads are taking to long. In that case, each new - * read will read the element the previous read returned. + * The last write is returned upon read. + * + * 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. * * @verbatim * The following Truth table applies when a Low Priority thread is * preempted by a High Priority thread : * * L\H | Set | Get | - * Set | Ok | Ok | + * Set | NA | Ok | * Get | Ok | Ok | * * legend : L : Low Priority thread * H : High Priority thread * Blk: Blocks High Priority thread (bad!) - * internal::NA : Not allowed ! + * internal::NA : Not allowed! * @endverbatim * Further, multiple reads may occur before, during and after * a write operation simultaneously. The buffer needs readers+2*writers - * elements to be guaranteed non blocking. + * elements to be guaranteed thread-safe (recall that writers==1). * @ingroup PortBuffers */ template<class T> @@ -199,7 +200,7 @@ namespace RTT * locking is needed. */ // writeout in any case - write_ptr->data = push; + write_ptr->data = push; // takes some time PtrType wrote_ptr = write_ptr; // if next field is occupied (by read_ptr or counter), // go to next and check again... @@ -207,7 +208,7 @@ namespace RTT { write_ptr = write_ptr->next; if (write_ptr == wrote_ptr) - return; // nothing found, to many readers ! + return; // nothing found, too many readers ! } // we will be able to move, so replace read_ptr -- 1.7.9.5