resourcesuser.h

/********************************************************************************
 *  FARSA Experiments Library                                                   *
 *  Copyright (C) 2007-2012                                                     *
 *  Gianluca Massera <emmegian@yahoo.it>                                        *
 *  Stefano Nolfi <stefano.nolfi@istc.cnr.it>                                   *
 *  Onofrio Gigliotta <onofrio.gigliotta@istc.cnr.it>                           *
 *  Tomassino Ferrauto <tomassino.ferrauto@istc.cnr.it>                         *
 *                                                                              *
 *  This program is free software; you can redistribute it and/or modify        *
 *  it under the terms of the GNU General Public License as published by        *
 *  the Free Software Foundation; either version 2 of the License, or           *
 *  (at your option) any later version.                                         *
 *                                                                              *
 *  This program is distributed in the hope that it will be useful,             *
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of              *
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               *
 *  GNU General Public License for more details.                                *
 *                                                                              *
 *  You should have received a copy of the GNU General Public License           *
 *  along with this program; if not, write to the Free Software                 *
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA  *
 ********************************************************************************/

#ifndef RESOURCESUSER_H
#define RESOURCESUSER_H

#include "parametersettable.h"
#include "configurationconfig.h"
#include "configurationexceptions.h"
#include "resource.h"
#include <QMap>
#include <QString>
#include <QStringList>
#include <QMutexLocker>
#include <QSet>

class QObject;

namespace farsa {

class ResourcesUser;
class SimpleResourcesUser;
class ConcurrentResourcesUser;
class ResourcesLocker;

class FARSA_CONF_API ResourcesUser : public  Resource
{
public:
    typedef Resource::ResourceChangeType ResourceChangeType;

public:
    virtual void shareResourcesWith(ResourcesUser* other);

protected:
    ResourcesUser();

    ResourcesUser(const ResourcesUser& other) throw();

    ResourcesUser& operator=(const ResourcesUser& other) throw();

    virtual ~ResourcesUser();

    virtual void notifyResourceChange(ResourceHandler* resource, ResourceChangeType changeType) = 0;

    ResourceCollectionHolder m_resources;

    friend class ResourceHandler;

    friend class ConcurrentResourcesUser;
};

class FARSA_CONF_API SimpleResourcesUser : public ResourcesUser
{
public:
    SimpleResourcesUser();

    SimpleResourcesUser(const SimpleResourcesUser& other);

    SimpleResourcesUser& operator=(const SimpleResourcesUser& other);

    virtual ~SimpleResourcesUser();

    virtual void shareResourcesWith(ResourcesUser* other);

    template<class T>
    void declareResource(QString name, T* resource)
    {
        // Now we have to get the resource (creating it if necessary). 
        ResourceHandler* h = m_resources->getResource(name, true);

        // Now setting the resource. If this throws an exception we could have simply created a non-existing
        // resource above that doesn't modify the external behaviour of this and other classes (so we can say
        // that this function is strongly exception-safe)
        h->set(resource);
    }

    template<class T>
    T* getResource(QString name)
    {
        // Trying to retrieve the resource
        ResourceHandler* h = m_resources->getResource(name, false);

        if ((h == NULL) || (!h->exists())){
            throw ResourceNotDeclaredException(name.toLatin1().data());
        }

        T* resource = h->get<T>();
        if (resource == NULL) {
            throw ResourceTypeMismatchException(name.toLatin1().data(), typeid(T).name());
        }

        return resource;
    }

    void deleteResource(QString name);

    bool hasResource(QString name) const
    {
        return m_resources->hasResource(name);
    }

protected:
    virtual void resourceChanged(QString name, ResourceChangeType changeType);

    template<class T>
    T* getResource()
    {
        if (!m_beingNotified) {
            return NULL;
        }

        if (!m_notifiedResourceHandler->exists()) {
            // The resource could have been deleted
            throw ResourceNotDeclaredException(m_notifiedResourceHandler->name().toLatin1().data());
        }
        T* resource = m_notifiedResourceHandler->get<T>();
        if (resource == NULL) {
            throw ResourceTypeMismatchException(m_notifiedResourceHandler->name().toLatin1().data(), typeid(T).name());
        }

        return resource;
    }

private:
    virtual void notifyResourceChange(ResourceHandler* resource, ResourceChangeType changeType);

    void removeAllNotifications();

    void forceBeingNotified();

    bool m_beingNotified;

    ResourceHandler* m_notifiedResourceHandler;

    QSet<ResourceHandler*> m_observedResources;
};

class FARSA_CONF_API ConcurrentResourcesUser : public ResourcesUser
{
public:
    ConcurrentResourcesUser();

    virtual ~ConcurrentResourcesUser();

    virtual void shareResourcesWith(ResourcesUser* buddy);

    void usableResources(QStringList resources);

    void addUsableResource(QString resource);

    void addUsableResources(QStringList resources);

    void removeUsableResource(QString resource);

    void removeUsableResources(QStringList resources);

    void removeAllUsableResources();

    template<class T>
    void declareResource(QString name, T* resource, QString lockBuddy = "")
    {
        if ((m_lockAcquired > 0) || m_beingNotified) {
            throw WrongResourceLockStatusForOperation("declareResource", true);
        }

        // Getting the lock on the resource collection
        QMutexLocker collectionLocker(&(m_resources->getLock()));

        // Now we have to get the resource (creating it if necessary) and then acquire the lock on the resource
        ResourceHandler* h = m_resources->getResource(name, true);
        if (!lockBuddy.isEmpty()) {
            ResourceHandler* lockBuddyHandler = m_resources->getResource(lockBuddy, false);
            if ((lockBuddyHandler == NULL) || (!lockBuddyHandler->exists())) {
                throw ResourceNotDeclaredException(lockBuddy.toLatin1().data());
            }
            h->shareLockWith(lockBuddyHandler);
        }
        ResourcesMutexesLocker resourceLocker(this, h);

        // Before setting the resource, we can release the lock on Resource Manager
        collectionLocker.unlock();

        // Now setting the resource (the lock on the resource has been acquired here and will be released after
        // returning from the following call)
        h->set(resource);
    }

    template<class T>
    T* getResource(QString name, bool* resourceExists = NULL)
    {
        if ((m_lockAcquired == 0) && ((!m_beingNotified) || (m_notifiedResourceHandler->name() != name))) {
            throw WrongResourceLockStatusForOperation("getResource", false);
        }

        if (!m_usableResources.contains(name)) {
            throw ResourceNotUsableException(name.toLatin1().data());
        }

        // Getting the resource. It could be non-existent, we have to check again
        if (resourceExists != NULL) {
            // This will be set to false after the check
            *resourceExists = true;
        }
        ResourceHandler* h = m_usableResources[name];
        if (!h->exists()) {
            if (resourceExists != NULL) {
                *resourceExists = false;

                return NULL;
            } else {
                throw ResourceNotDeclaredException(name.toLatin1().data());
            }
        }

        T* resource = h->get<T>();
        if (resource == NULL) {
            throw ResourceTypeMismatchException(name.toLatin1().data(), typeid(T).name());
        }

        return resource;
    }

    void deleteResource(QString name);

    bool hasResource(QString name) const;

    bool usedResourcesExist(QStringList* nonExistingResources = NULL) const;

protected:
    virtual void resourceChanged(QString name, ResourceChangeType changeType);

    template<class T>
    T* getResource()
    {
        if (!m_beingNotified) {
            if (m_lockAcquired > 0) {
                return NULL;
            } else {
                throw WrongResourceLockStatusForOperation("getResource (inside resourceChanged())", false);
            }
        }

        if (!m_notifiedResourceHandler->exists()) {
            // The resource could have been deleted
            throw ResourceNotDeclaredException(m_notifiedResourceHandler->name().toLatin1().data());
        }
        T* resource = m_notifiedResourceHandler->get<T>();
        if (resource == NULL) {
            throw ResourceTypeMismatchException(m_notifiedResourceHandler->name().toLatin1().data(), typeid(T).name());
        }

        return resource;
    }

private:
    void lockAll();

    void unlockAll();

    virtual void notifyResourceChange(ResourceHandler* resource, ResourceChangeType changeType);

    void removeAllNotifications();

    void forceBeingNotified();

    void lockResources(const QList<ResourceHandler*>& resources);

    void unlockResources(const QList<ResourceHandler*>& resources);

    class ResourcesMutexesLocker
    {
    public:
        ResourcesMutexesLocker(ConcurrentResourcesUser *resourcesUser, const QList<ResourceHandler *>& resources) :
            m_resourcesUser(resourcesUser),
            m_resources(resources)
        {
            m_resourcesUser->lockResources(m_resources);
        }

        ResourcesMutexesLocker(ConcurrentResourcesUser *resourcesUser, ResourceHandler* resource) :
            m_resourcesUser(resourcesUser),
            m_resources(QList<ResourceHandler *>() << resource)
        {
            m_resourcesUser->lockResources(m_resources);
        }

        ~ResourcesMutexesLocker()
        {
            m_resourcesUser->unlockResources(m_resources);
        }

    private:
        ConcurrentResourcesUser *const m_resourcesUser;

        QList<ResourceHandler *> m_resources;
    };

    unsigned int m_lockAcquired;

    bool m_beingNotified;

    ResourceHandler* m_notifiedResourceHandler;

    QMap<QString, ResourceHandler*> m_usableResources;

    ConcurrentResourcesUser(const ConcurrentResourcesUser& other);

    ConcurrentResourcesUser& operator=(const ConcurrentResourcesUser& other);

    friend class ResourcesLocker;
};

class FARSA_CONF_API ResourcesLocker
{
public:
    ResourcesLocker(ConcurrentResourcesUser *resourcesUser, bool acquireLock = true);

    ~ResourcesLocker();

    void lock();

    void unlock();

private:
    ConcurrentResourcesUser *const m_resourcesUser;

    bool m_lockedByUs;
};

} // end namespace farsa

#endif