store.h

/*
 * GearBox Project: Peer-Reviewed Open-Source Libraries for Robotics
             http://gearbox.sf.net/
 * Copyright (c) 2004-2010 Alex Brooks, Alexei Makarenko, Tobias Kaupp
 *
 * This distribution is licensed to you under the terms described in
 * the LICENSE file included in this distribution.
 *
 */

#ifndef GBXICEUTILACFR_STORE_H
#define GBXICEUTILACFR_STORE_H

#include <gbxutilacfr/exceptions.h>

#include <IceUtil/Monitor.h>
#include <IceUtil/Mutex.h>
#include <IceUtil/Time.h>

namespace gbxiceutilacfr {

template<class Type>
class Store : public IceUtil::Monitor<IceUtil::Mutex>
{
public:

    Store();
    virtual ~Store();

    bool isEmpty() const;
    
    bool isNewData() const;

    void set( const Type & obj );

    void get( Type & obj );

    void peek( Type & obj ) const;

    int  getNext( Type & obj, int timeoutMs=-1 );
    
    void purge();

protected:
    
    // local copy of the object
    Type obj_;

    // Reimplement this function for non-standard types.
    virtual void internalGet( Type & obj ) const ;
    
    // Reimplement this function for non-standard types.
    virtual void internalSet( const Type & obj );

private:


    bool isEmpty_;
    
    // flag to keep track of new data.
    bool isNewData_;

    // internal implementation of front( obj, -1 ); returns 0.
    int  getNextNoWait( Type & obj );

};



template<class Type>
Store<Type>::Store()
    : isEmpty_(true),
      isNewData_(false)
{
}

template<class Type>
Store<Type>::~Store()
{
}

template<class Type>
bool Store<Type>::isEmpty() const
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);
    return isEmpty_;
}

template<class Type>
bool Store<Type>::isNewData() const
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);
    return isNewData_;
}

template<class Type>
void Store<Type>::get( Type & obj )
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);
    if ( !isEmpty_ )
    {
        internalGet( obj );
        isNewData_ = false;
    }
    else
    {
        throw gbxutilacfr::Exception( ERROR_INFO, "trying to read from an empty Store." );
    }
}

template<class Type>
void Store<Type>::peek( Type & obj ) const
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);
    if ( !isEmpty_ )
    {
        internalGet( obj );
        // do NOT set isNewData_ to false
    }
    else
    {
        throw gbxutilacfr::Exception( ERROR_INFO, "trying to read from an empty Store." );
    }
}

template<class Type>
int Store<Type>::getNext( Type & obj, int timeoutMs )
{
    // special case: infinite wait time
    if ( timeoutMs == -1 ) {
        return getNextNoWait( obj );
    }

    // finite wait time
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);

    // if already have data in the buffer, return it and get out
    if ( isNewData_ )
    {
        internalGet( obj );
        isNewData_ = false;
        return 0;
    }

    // empty buffer: figure out when to wake up
    // notice that we are still holding the lock, so it's ok to call timedWait()
    if (  this->timedWait( IceUtil::Time::milliSeconds( timeoutMs ) ) )  
    {
        // someone woke us up, we are holding the lock again
        // check new data again (could be a spurious wakeup)
        if ( isNewData_ ) 
        {
            internalGet( obj );
            isNewData_ = false;
            return 0;
        }
        else {
            // spurious wakup, don't wait again, just return
            return 1;
        }
    }
    else {
        // wait timedout, nobody woke us up
        return -1;
    }
}

template<class Type>
int Store<Type>::getNextNoWait( Type & obj )
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);

    // check the condition before and after waiting to deal with spurious wakeups
    // (see Ice manual sec. 28.9.2)
    while ( !isNewData_ ) 
    {
        this->wait();
    }
   
    internalGet( obj );
    isNewData_ = false;
    return 0;
}

// NOTE: see notes on efficient notification in Ice sec. 28.9.3
template<class Type>
void Store<Type>::set( const Type &obj )
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);
    
    internalSet( obj );

    // mark as having new data (nobody has looked at it yet)
    isNewData_ = true;
    
    // mark Store non-empty (only usefull the very first time)
    isEmpty_ = false;
    
    // wakeup someone who's waiting for an update
    this->notify();
}

template<class Type>
void Store<Type>::purge()
{
    IceUtil::Monitor<IceUtil::Mutex>::Lock lock(*this);
    isEmpty_ = true;
}

template<class Type>
void Store<Type>::internalGet( Type & obj ) const
{
    obj = obj_;
}

template<class Type>    
void Store<Type>::internalSet( const Type & obj )
{
    obj_ = obj;
}

} // end namespace

#endif