osaTripleBuffer.h

Go to the documentation of this file.

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-    */
/* ex: set filetype=cpp softtabstop=4 shiftwidth=4 tabstop=4 cindent expandtab: */

/*

  Author(s): Martin Kelly, Anton Deguet
  Created on: 2011-03-15

  (C) Copyright 2011 Johns Hopkins University (JHU), All Rights
  Reserved.

--- begin cisst license - do not edit ---

This software is provided "as is" under an open source license, with
no warranty.  The complete license can be found in license.txt and
http://www.cisst.org/cisst/license.txt.

--- end cisst license ---

*/

#include <cisstConfig.h> // to define CISST_OS and CISST_COMPILER

#include <cisstCommon/cmnAssert.h>
#include <cisstOSAbstraction/osaMutex.h>

template <class _elementType>
class osaTripleBuffer
{
    friend class osaTripleBufferTest;

    typedef _elementType value_type;

    typedef osaTripleBuffer<value_type> ThisType;

    typedef value_type * pointer;
    typedef const value_type * const_pointer;
    typedef value_type & reference;
    typedef const value_type & const_reference;

    // did the buffer allocate memory or used existing pointers
    bool OwnMemory;
    pointer Memory;

    // circular buffer node
    class Node {
    public:
        Node(const pointer data):
            Pointer(data) {}
        pointer Pointer;
        Node * Next;
    };

    typedef Node * NodePointer;

    // last write node (behaves like a head in our lifo circular buffer
    volatile NodePointer LastWriteNode;
    volatile NodePointer WriteNode;
    volatile NodePointer ReadNode;

    // bool for debug
    bool LastCompare;

    // to make sure the ReadNode is thread safe
    osaMutex Mutex;


public:
    inline osaTripleBuffer(void):
        OwnMemory(true)
    {
        this->Memory = new value_type[3];
        SetupNodes(this->Memory,
                   this->Memory + 1,
                   this->Memory + 2);
    }

    inline osaTripleBuffer(const_reference initialValue):
        OwnMemory(true),
        Memory(0)
    {
        SetupNodes(new value_type(initialValue),
                   new value_type(initialValue),
                   new value_type(initialValue));
    }

    inline osaTripleBuffer(pointer pointer1, pointer pointer2, pointer pointer3):
        OwnMemory(false),
        Memory(0)
    {
        SetupNodes(pointer1, pointer2, pointer3);
    }

    inline void SetupNodes(pointer pointer1, pointer pointer2, pointer pointer3) {
        CMN_ASSERT(pointer1);
        CMN_ASSERT(pointer2);
        CMN_ASSERT(pointer3);
        this->ReadNode = 0;
        this->WriteNode = 0;
        this->LastWriteNode = new Node(pointer1);
        this->LastWriteNode->Next = new Node(pointer2);
        this->LastWriteNode->Next->Next = new Node(pointer3);
        this->LastWriteNode->Next->Next->Next = this->LastWriteNode;
    }

    inline ~osaTripleBuffer() {
        // free memory if we own it
        if (this->OwnMemory) {
            // can be an array or three different pointers
            if (this->Memory) {
                delete[] this->Memory;
            } else {
                delete this->LastWriteNode->Next->Next->Pointer;
                delete this->LastWriteNode->Next->Pointer;
                delete this->LastWriteNode->Pointer;
            }
        }
        // free nodes
        delete this->LastWriteNode->Next->Next;
        delete this->LastWriteNode->Next;
        delete this->LastWriteNode;
    }

    inline void Read(reference placeHolder) {
        this->BeginRead();
        placeHolder = *(ReadNode->Pointer);
        this->EndRead();
    }

    inline void Write(const_reference newValue) {
        this->BeginWrite();
        *(WriteNode->Pointer) = newValue;
        this->EndWrite();
    }

    inline const_pointer GetReadPointer(void) const {
        return this->ReadNode->Pointer;
    }

    inline pointer GetWritePointer(void) const {
        return this->WriteNode->Pointer;
    }

    inline void BeginRead(void) {
        Mutex.Lock(); {
            this->ReadNode = this->LastWriteNode;
        } Mutex.Unlock();
    }

    inline void EndRead(void) {
        Mutex.Lock(); {
            this->ReadNode = 0;
        } Mutex.Unlock();
    }


    inline void BeginWrite(void) {
        this->WriteNode = this->LastWriteNode->Next;
        Mutex.Lock(); {
            LastCompare = (this->WriteNode == this->ReadNode);
            if (LastCompare) {
                this->WriteNode = this->WriteNode->Next;
            }
        } Mutex.Unlock();
    }


    inline void EndWrite(void) {
        this->LastWriteNode = this->WriteNode;
    }


    void ToStream(std::ostream & outputStream) const {
        outputStream << "Node addresses from LastWriteNode: "
                     << this->LastWriteNode << "[" << this->LastWriteNode->Pointer << "] "
                     << this->LastWriteNode->Next << "[" << this->LastWriteNode->Next->Pointer << "] "
                     << this->LastWriteNode->Next->Next << "[" << this->LastWriteNode->Next->Next->Pointer << "]" << std::endl
                     << "LastCompare of read/write: " << ((this->LastCompare) ? "equal" : "different") << std::endl
                     << "ReadNode address: " << this->ReadNode << std::endl
                     << "WriteNode address: " << this->WriteNode << std::endl;
    }
};