AbstractChannel.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_ABSTRACTCHANNEL_H_
#define _MIRA_ABSTRACTCHANNEL_H_

#ifndef Q_MOC_RUN
#include <boost/thread/mutex.hpp>
#endif

#include <error/Exceptions.h>

#include <fw/AbstractChannelSubscriber.h>
#include <fw/ChannelBuffer.h>

namespace mira {


class MIRA_FRAMEWORK_EXPORT AbstractChannel : boost::noncopyable
{
public:

    typedef ChannelBufferBase::Slot Slot;

public:

    AbstractChannel(const std::string& id, ChannelBufferBase* buffer);

    ~AbstractChannel();

public:

    const std::string& getID() const { return mID; }

public:

    int getTypeId() const { return mBuffer->getTypeId(); }

    Typename getTypename() const { return mBuffer->getTypename(); }

    void setTypename(const Typename& name) { mBuffer->setTypename(name); }

    TypeMetaPtr getTypeMeta() const { return mBuffer->getTypeMeta(); }

    void setTypeMeta(TypeMetaPtr meta) { mBuffer->setTypeMeta(meta); }

    void fixateType() { mBuffer->fixateType(); }

    bool isTyped() const { return mBuffer->isTyped(); }

    ChannelBufferBase* getBuffer() { return mBuffer; }

    std::size_t getNrOfSlots() const { return mBuffer->getSize(); }

    Time getLastSlotTime() const { return mLastSlotTime; }

    uint64 getNrOfDataChanges() const { return mNrOfDataChanges; }

public:

    bool hasSubscriber() const {
        return !mSubscribers.empty() || mNrOfSubscribersWithoutChannelSubscriber > 0; 
    }


    bool hasPublisher() const;

    void removeSubscriber();

    void removeSubscriber(AbstractChannelSubscriberPtr subscriber);

public:

    void finishWrite(Slot* s);

    void discardWrite(Slot* s);

public:

    template<typename TargetType>
    void promote()
    {
        boost::mutex::scoped_lock lock(mPromoteMutex);
        ChannelBufferBase* oldBuffer = mBuffer;

        // promote our buffer, this may create a new buffer if necessary
        // then we set the new buffer and destroy the old one afterwards
        ChannelBufferBase* newBuffer;
        try {
            newBuffer = mBuffer->promote<TargetType>();
        }
        catch(Exception& ex) {
            MIRA_RETHROW(ex, "while trying to promote channel '" << this->getID() << "'")
        }

        if(newBuffer!=oldBuffer) {
            // TODO: the next assignment is atomic, hence there should be no
            // threading problem, even if someone obtains a ChannelRead or
            // ChannelWrite within the next line. (using a mutex here and in the
            // read() and write() methods would be even safer, but would also add
            // some more overhead.)
            mBuffer = newBuffer; // assign the new buffer

            // do not delete the old buffer here, as there might be
            // someone who still holds a lock to a slot. Instead, the buffer
            // will be freed when this AbstractChannel is destructed.
            // An alternative would be to use a shared_ptr for mBuffer and
            // to pass it to the ChannelReadWrite objects.
            mUntypedBuffer = oldBuffer;
        }
    }

public:

    void dbgDump(bool brief=true) { mBuffer->dbgDump(mID, brief); }

protected:

    std::string mID;
    ChannelBufferBase* mBuffer;
    ChannelBufferBase* mUntypedBuffer;

    boost::mutex mPromoteMutex;
    boost::mutex mSubscribersMutex;
    std::list<AbstractChannelSubscriberPtr > mSubscribers;
    uint32 mNrOfSubscribersWithoutChannelSubscriber; // number of subscribers that are subscribed without callback
    Time mLastSlotTime;
    uint64 mNrOfDataChanges;
};

typedef AbstractChannel* AbstractChannelPtr;



template<typename TargetType>
inline void promote_channel(AbstractChannelPtr channel)
{
    channel->promote<TargetType>();
}

template<>
inline void promote_channel<void>(AbstractChannelPtr channel)
{
    // Do nothing if target type is void (untyped channel). 
    // We can only promote to non-void typed channels.
}



}

#endif