include/dlvhex2/PluginInterface.h

Go to the documentation of this file.

/* dlvhex -- Answer-Set Programming with external interfaces.
 * Copyright (C) 2005-2007 Roman Schindlauer
 * Copyright (C) 2006-2015 Thomas Krennwallner
 * Copyright (C) 2009-2016 Peter Schüller
 * Copyright (C) 2011-2016 Christoph Redl
 * Copyright (C) 2015-2016 Tobias Kaminski
 * Copyright (C) 2015-2016 Antonius Weinzierl
 *
 * This file is part of dlvhex.
 *
 * dlvhex is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * dlvhex 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with dlvhex; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA.
 */

#if !defined(_DLVHEX_PLUGININTERFACE_H)
#define _DLVHEX_PLUGININTERFACE_H

#include "dlvhex2/PlatformDefinitions.h"
#include "dlvhex2/fwd.h"
#include "dlvhex2/ID.h"
#include "dlvhex2/Atoms.h"
#include "dlvhex2/Error.h"
#include "dlvhex2/CDNLSolver.h"
#include "dlvhex2/ComponentGraph.h"
#include "dlvhex2/ExtSourceProperties.h"
#include "dlvhex2/ExternalAtomEvaluationHeuristicsInterface.h"

#include <boost/shared_ptr.hpp>
#include <boost/unordered_map.hpp>
#include <boost/thread/mutex.hpp>

#include <map>
#include <string>
#include <iosfwd>
#include <algorithm>

#include <boost/shared_ptr.hpp>
#include <boost/unordered_map.hpp>

#define PLUGINABIVERSIONFUNCTION getDlvhex2ABIVersion
#define PLUGINABIVERSIONFUNCTIONSTRING "getDlvhex2ABIVersion"

#define PLUGINVERSIONFUNCTION getDlvhexPluginVersion
#define PLUGINVERSIONFUNCTIONSTRING "getDlvhexPluginVersion"
#define PLUGINIMPORTFUNCTION importPlugin
#define PLUGINIMPORTFUNCTIONSTRING "importPlugin"
#define IMPLEMENT_PLUGINABIVERSIONFUNCTION \
    extern "C" DLVHEX_PLUGINEXPORT int PLUGINABIVERSIONFUNCTION() \
    { \
        return DLVHEX_ABI_VERSION_MAJOR*10000+\
        DLVHEX_ABI_VERSION_MINOR*100+\
        DLVHEX_ABI_VERSION_MICRO; \
    }

DLVHEX_NAMESPACE_BEGIN

class DLVHEX_EXPORT PluginInterface
{
    protected:
        PluginInterface():
        pluginName(),
            versionMajor(0),
            versionMinor(0),
            versionMicro(0)
            { }

        std::string pluginName;
        unsigned versionMajor;
        unsigned versionMinor;
        unsigned versionMicro;

        void setNameVersion(
            const std::string& name, unsigned major,
        unsigned minor, unsigned micro) {
            pluginName = name;
            versionMajor = major;
            versionMinor = minor;
            versionMicro = micro;
        }

    public:
        virtual ~PluginInterface() {}

        virtual std::vector<PluginAtomPtr> createAtoms(ProgramCtx& ctx) const;

        virtual void printUsage(std::ostream& o) const;

        virtual void processOptions(std::list<const char*>& pluginOptions, ProgramCtx& ctx);

        virtual PluginConverterPtr createConverter(ProgramCtx&);

        virtual std::vector<PluginConverterPtr> createConverters(ProgramCtx& ctx);

        virtual bool providesCustomModelGeneratorFactory(ProgramCtx& ctx) const { return false; }

        virtual BaseModelGeneratorFactoryPtr getCustomModelGeneratorFactory(ProgramCtx& ctx, const ComponentGraph::ComponentInfo& ci) const
            { assert(false && "This plugin does not provide a custom model generator factory"); return BaseModelGeneratorFactoryPtr(); }

        virtual std::vector<HexParserModulePtr> createParserModules(ProgramCtx&);

        virtual HexParserPtr createParser(ProgramCtx&);

        virtual PluginRewriterPtr createRewriter(ProgramCtx&);

        virtual PluginOptimizerPtr createOptimizer(ProgramCtx&);

        virtual void setupProgramCtx(ProgramCtx&) {  }

        const std::string& getPluginName() const
            { return this->pluginName; }
        unsigned getVersionMajor() const
            { return this->versionMajor; }
        unsigned getVersionMinor() const
            { return this->versionMinor; }
        unsigned getVersionMicro() const
            { return this->versionMicro; }

};
// beware: most of the time this Ptr will have to be created with a "deleter" in the library
typedef boost::shared_ptr<PluginInterface> PluginInterfacePtr;

class PluginData
{
    public:
        PluginData() {}
        virtual ~PluginData() {}
};
typedef boost::shared_ptr<PluginData> PluginDataPtr;

class PluginEnvironment
{
    public:
        PluginEnvironment() {}
        virtual ~PluginEnvironment() {}
};
typedef boost::shared_ptr<PluginEnvironment> PluginEnvironmentPtr;

class DLVHEX_EXPORT PluginAtom
{
    public:
        struct DLVHEX_EXPORT Query
        {
            const ProgramCtx* ctx;

            InterpretationConstPtr interpretation;

            InterpretationConstPtr assigned;

            InterpretationConstPtr changed;

            Tuple input;

            Tuple pattern;

            ID eatomID;

            InterpretationPtr predicateInputMask;

            Query(const ProgramCtx* ctx,
                InterpretationConstPtr interpretation,
                const Tuple& input,
                const Tuple& pattern,
                ID eatomID = ID_FAIL,
                const InterpretationPtr predicateInputMask = InterpretationPtr(),
                const InterpretationConstPtr assigned = InterpretationConstPtr(),
                const InterpretationConstPtr changed = InterpretationConstPtr()):
            ctx(ctx),
                interpretation(interpretation),
                input(input),
                pattern(pattern),
                eatomID(eatomID),
                predicateInputMask(predicateInputMask),
                assigned(assigned),
            changed(changed) {
            }
            void assign(const Query& q2);
            bool operator==(const Query& other) const;
        };

        struct DLVHEX_EXPORT Answer
        {
            Answer();

            std::vector<Tuple>& get() { used = true; return *output; }

            const std::vector<Tuple>& get() const { return *output; }

            std::vector<Tuple>& getUnknown() { used = true; return *unknown; }

            const std::vector<Tuple>& getUnknown() const { return *unknown; }

            bool hasBeenUsed() const { return used; }

            void use() { used = true; }

            Answer& operator=(const Answer& other)
                { output = other.output; unknown = other.unknown; used = true; return *this; }

            bool operator==(const Answer& other) const;

            private:
                // \brief stores the positive output values; shared_ptr storage for have low-cost-copying of this object and for a more efficient query answer cache implementation.
                boost::shared_ptr<std::vector<Tuple> > output;
                // \brief stores the unknown output values (those neither in output nor in unknown are false); shared_ptr storage for have low-cost-copying of this object and for a more efficient query answer cache implementation.
                boost::shared_ptr<std::vector<Tuple> > unknown;
                // usage marker: true if this was default-constructed and never used
                bool used;
        };

        typedef enum {
            PREDICATE,
            CONSTANT,
            TUPLE
        } InputType;

    protected:
        PluginAtom(const std::string& predicate, bool monotonic):
        predicate(predicate),
        allmonotonic(monotonic) {
            prop.pa = this;
        }

        // The following functions are to be used in the constructor only.

        void addInputPredicate(bool nameIsRelevant = false);

        void addInputConstant();

        void addInputTuple();

        void setOutputArity(unsigned arity);

    public:
        virtual ~PluginAtom() {}

        int getInputArity() const;

        int getOutputArity() const;

        bool checkInputArity(unsigned arity) const;

        bool checkOutputArity(const ExtSourceProperties& prop, unsigned arity) const;

        virtual void setupProperties(const ExternalAtom& eatom) {}

        virtual void guardSupportSet(bool& keep, Nogood& ng, const ID eaReplacement) { assert(ng.isGround()); keep = true; }

        bool retrieveFacade(const Query& query, Answer& answer, NogoodContainerPtr nogoods, bool useCache);

        virtual bool retrieveCached(const Query& query, Answer& answer, NogoodContainerPtr nogoods);

        virtual void retrieve(const Query& query, Answer& answer, NogoodContainerPtr nogoods);

        virtual void retrieve(const Query& query, Answer& answer);

        virtual void learnSupportSets(const Query& query, NogoodContainerPtr nogoods);

        virtual void generalizeNogood(Nogood ng, ProgramCtx* ctx, NogoodContainerPtr nogoods);

        virtual std::vector<Query> splitQuery(const Query& query, const ExtSourceProperties& prop);

        InputType getInputType(unsigned index) const;

        const std::vector<InputType>& getInputTypes() const
            { return inputType; }

        virtual bool providesCustomExternalAtomEvaluationHeuristicsFactory() const { return false; }

        virtual ExternalAtomEvaluationHeuristicsFactoryPtr getCustomExternalAtomEvaluationHeuristicsFactory() const
            { assert(false && "This plugin atom does not provide a custom external atom evaluation heuristics factory"); return ExternalAtomEvaluationHeuristicsFactoryPtr(); }

        const ExtSourceProperties& getExtSourceProperties() const
        {
            return prop;
        }

        // Associate plugin atom with registry pointer.
        // (This implicitly calculates the predicate ID.)

        virtual void setRegistry(RegistryPtr reg);

        RegistryPtr getRegistry() const
            { return registry; }

        ID getPredicateID() const
            { return predicateID; }

        const std::string& getPredicate() const
            { return predicate; }

        PredicateMaskPtr getReplacements(){ replacements->updateMask(); return replacements; }

        void resetCache() {
            queryAnswerNogoodCache.clear();
        }

    protected:
        // \brief Predicate of the atom as it appears in HEX programs (without leading &)
        //
        // This is not stored as ID, because plugins must be allowed to create
        // atoms without knowing the registry they will be used with.
        //
        // Calling setRegistry provides the predicate ID.
        std::string predicate;

        ID predicateID;

        bool allmonotonic;

        ExtSourceProperties prop;

        std::vector<InputType> inputType;

        unsigned outputSize;

        // Query/Answer cache
        typedef boost::unordered_map<const Query, std::pair<Answer, SimpleNogoodContainerPtr> > QueryAnswerNogoodCache;
        typedef boost::unordered_map<const Query, SimpleNogoodContainerPtr> QueryNogoodCache;
        QueryAnswerNogoodCache queryAnswerNogoodCache;
        boost::mutex cacheMutex;

        PredicateMaskPtr replacements;

        std::vector<Tuple> otuples;

        RegistryPtr registry;

    private:
        PluginAtom(const PluginAtom& pa){}

        const PluginAtom& operator=(const PluginAtom& pa){ return *this; }
};

typedef boost::shared_ptr<PluginAtom> PluginAtomPtr;
typedef boost::weak_ptr<PluginAtom> PluginAtomWeakPtr;
// hash function for QueryAnswerCache
std::size_t hash_value(const PluginAtom::Query& q);

class DLVHEX_EXPORT PluginConverter
{
    public:
        virtual ~PluginConverter() { }

        virtual void convert(std::istream& i, std::ostream& o) = 0;
};
typedef boost::shared_ptr<PluginConverter> PluginConverterPtr;

class ModelCallback:
public std::unary_function<bool, AnswerSetPtr>
{
    public:
        virtual ~ModelCallback() {}
        virtual bool operator()(AnswerSetPtr as) = 0;
};
typedef boost::shared_ptr<ModelCallback> ModelCallbackPtr;

class FinalCallback
{
    public:
        virtual ~FinalCallback() {}
        virtual void operator()() = 0;
};
typedef boost::shared_ptr<FinalCallback> FinalCallbackPtr;

class DLVHEX_EXPORT PluginRewriter
{
    protected:
        PluginRewriter() {}

    public:
        virtual ~PluginRewriter() {}

        virtual void rewrite(ProgramCtx& ctx) = 0;
};
typedef boost::shared_ptr<PluginRewriter> PluginRewriterPtr;

class DLVHEX_EXPORT PluginOptimizer
{
    public:
        virtual ~PluginOptimizer() {}

        virtual void optimize(InterpretationPtr edb, DependencyGraphPtr depgraph) = 0;
};

//
// deleters
//

template<typename AllocatedT>
struct PluginPtrDeleter
{
    PluginPtrDeleter() {}
    inline void operator()(const AllocatedT* ptr) const
    {
        delete ptr;
    }
};

template<typename AllocatedT>
struct PluginPtrNOPDeleter
{
    PluginPtrNOPDeleter() {}
    inline void operator()(const AllocatedT* ptr) const
    {
        // NOP = do not delete
    }
};

DLVHEX_NAMESPACE_END
#endif                           // _DLVHEX_PLUGININTERFACE_H


// vim:expandtab:ts=4:sw=4:
// mode: C++
// End: