Factory where plugins interact with the dlvhex core. More...

#include <include/dlvhex2/PluginInterface.h>

Inheritance diagram for PluginInterface:

Collaboration diagram for PluginInterface:

Public Member Functions
virtual	~PluginInterface ()
virtual std::vector < PluginAtomPtr >	createAtoms (ProgramCtx &ctx) const
	Publish external computation sources to dlvhex.
virtual void	printUsage (std::ostream &o) const
	Output help message for this plugin.
virtual void	processOptions (std::list< const char * > &pluginOptions, ProgramCtx &ctx)
	Processes options for this plugin.
virtual PluginConverterPtr	createConverter (ProgramCtx &)
	Provide PluginConverter.
virtual std::vector < PluginConverterPtr >	createConverters (ProgramCtx &ctx)
	Provide multiple PluginConverter objects.
virtual bool	providesCustomModelGeneratorFactory (ProgramCtx &ctx) const
	Returns if this plugin provides a custom evaluation heuristics for a certain external atom.
virtual BaseModelGeneratorFactoryPtr	getCustomModelGeneratorFactory (ProgramCtx &ctx, const ComponentGraph::ComponentInfo &ci) const
	Must create a model generator factory for the component described by ci.
virtual std::vector < HexParserModulePtr >	createParserModules (ProgramCtx &)
	Provide parser modules.
virtual HexParserPtr	createParser (ProgramCtx &)
	Provide alternative parser.
virtual PluginRewriterPtr	createRewriter (ProgramCtx &)
	Rewriter for hex-programs.
virtual PluginOptimizerPtr	createOptimizer (ProgramCtx &)
	Optimizer: may optimize dependency graph.
virtual void	setupProgramCtx (ProgramCtx &)
	Altering the ProgramCtx permits plugins to do many things, e.g., * installing model and finish callbacks * removing default model (and final) hooks * setting maxint * changing and configuring the solver backend to be used See internal plugins for example usage.
const std::string &	getPluginName () const
unsigned	getVersionMajor () const
unsigned	getVersionMinor () const
unsigned	getVersionMicro () const
Protected Member Functions
	PluginInterface ()
	Constructor.
void	setNameVersion (const std::string &name, unsigned major, unsigned minor, unsigned micro)
	Set plugin name and version (informative, this is not the ABI version).
Protected Attributes
std::string	pluginName
unsigned	versionMajor
unsigned	versionMinor
unsigned	versionMicro

Detailed Description

Factory where plugins interact with the dlvhex core.

Overview

The PluginInterface class can be seen as a wrapper for all user-defined features of a plugin, which are:

announce external atoms
supply convert/rewrite/parse/optimize facilities
supply model and final callbacks
offer help messages and command line options

You shall derive from PluginInterface in order to implement a plugin, the constructor shall set name and version of the plugin, preferrably defined in configure.ac using DLVHEX_DEFINE_VERSION. (See dlvhex-stringplugin for an example.)

Importing the Plugin

To make the plugin available, we need to instantiate it. The simplest way to do this is to define a global variable and the following code: Assume your plugin class is RDFPlugin derived from PluginInterface and you have

   RDFPlugin theRDFPlugin;

Then you publish theRDFPlugin to dlvhex as follows:

   extern "C"
   void* PLUGINIMPORTFUNCTION()
   {
     return reinterpret_cast<void*>(&theRDFPlugin);
   }

Definition at line 313 of file PluginInterface.h.

Constructor & Destructor Documentation

PluginInterface::PluginInterface ( ) [inline, protected]

Constructor.

Write your own constructor and set the version using setNameVersion().

Definition at line 321 of file PluginInterface.h.

virtual PluginInterface::~PluginInterface ( ) [inline, virtual]

Definition at line 356 of file PluginInterface.h.

Member Function Documentation

std::vector< PluginAtomPtr > PluginInterface::createAtoms ( ProgramCtx & ctx ) const [virtual]

Publish external computation sources to dlvhex.

This is the central location where the user's atoms are made public. dlvhex will call this function for all found plugins, which write their atoms in the provided map. This map associates strings with pointers to PluginAtom objects. The strings denote the name of the atom as it should be used in the program.

Override this method to publish your atoms.

Example:

   std::vector<PluginAtomPtr>
   createAtoms(ProgramCtx& ctx) const
   {
    std::vector<PluginAtomPtr> ret;
      PluginAtomPtr newatom1(new MyAtom1);
      PluginAtomPtr newatom2(new MyAtom2);
      ret["newatom1"] = newatom1;
      ret["newatom2"] = newatom2;
      return ret;
   }

Here, we assume to have defined atoms MyAtom1 and MyAtom2 derived from PluginAtom. These atom can now be used in a HEX-program with the predicate &newatom1[]() and &newatom2[]().

Reimplemented in TestPlugin, AggregatePlugin, FunctionPlugin, WeakConstraintPlugin, ChoicePlugin, and ConditionalLiteralPlugin.

Definition at line 676 of file PluginInterface.cpp.

PluginConverterPtr PluginInterface::createConverter ( ProgramCtx & ) [virtual]

Provide PluginConverter.

This method is called by createConverters, so if you overload createConverters, do not overload createConverter.

See PluginConverter documentation.

Definition at line 698 of file PluginInterface.cpp.

std::vector< PluginConverterPtr > PluginInterface::createConverters ( ProgramCtx & ctx ) [virtual]

Provide multiple PluginConverter objects.

This method calls createConverter, you can override it to provide multiple converters.

See PluginConverter documentation.

Definition at line 705 of file PluginInterface.cpp.

PluginOptimizerPtr PluginInterface::createOptimizer ( ProgramCtx & ) [virtual]

Optimizer: may optimize dependency graph.

Definition at line 735 of file PluginInterface.cpp.

HexParserPtr PluginInterface::createParser ( ProgramCtx & ) [virtual]

Provide alternative parser.

This method can be overwritten to provide an alternative HEX parser, e.g., for implementing slightly changed input syntax.

Definition at line 723 of file PluginInterface.cpp.

std::vector< HexParserModulePtr > PluginInterface::createParserModules ( ProgramCtx & ) [virtual]

Provide parser modules.

This is the preferred way to extend the input language by supplying dlvhex with parser modules that plug into the HEX grammar and extend the syntax for valid program input.

See the QueryPlugin and the StrongNegationPlugin for example plugins that use this feature.

Reimplemented in QueryPlugin, ManualEvalHeuristicsPlugin, HigherOrderPlugin, StrongNegationPlugin, FunctionPlugin, ChoicePlugin, and ConditionalLiteralPlugin.

Definition at line 717 of file PluginInterface.cpp.

PluginRewriterPtr PluginInterface::createRewriter ( ProgramCtx & ) [virtual]

Rewriter for hex-programs.

The rewriters are called on the parsed HEX program (which may have been rewritten by a PluginConverter). Hence, a rewriter can expect a well-formed HEX-program represented in ProgramCtx::edb and ProgramCtx::idb as input and must of course also take care of keeping that representation correct program.

Reimplemented in QueryPlugin, HigherOrderPlugin, ManualEvalHeuristicsPlugin, StrongNegationPlugin, AggregatePlugin, FunctionPlugin, and WeakConstraintPlugin.

Definition at line 729 of file PluginInterface.cpp.

virtual BaseModelGeneratorFactoryPtr PluginInterface::getCustomModelGeneratorFactory	(	ProgramCtx &	ctx,
		const ComponentGraph::ComponentInfo &	ci
	)		const `[inline, virtual]`

Must create a model generator factory for the component described by ci.

Needs to be implemented only if PluginAtom::providesCustomModelGeneratorFactory return true;

Definition at line 437 of file PluginInterface.h.

const std::string& PluginInterface::getPluginName ( ) const [inline]

Definition at line 485 of file PluginInterface.h.

unsigned PluginInterface::getVersionMajor ( ) const [inline]

Definition at line 487 of file PluginInterface.h.

unsigned PluginInterface::getVersionMicro ( ) const [inline]

Definition at line 491 of file PluginInterface.h.

unsigned PluginInterface::getVersionMinor ( ) const [inline]

Definition at line 489 of file PluginInterface.h.

void PluginInterface::printUsage ( std::ostream & o ) const [virtual]

Output help message for this plugin.

Reimplemented in QueryPlugin, HigherOrderPlugin, StrongNegationPlugin, ManualEvalHeuristicsPlugin, AggregatePlugin, FunctionPlugin, WeakConstraintPlugin, ChoicePlugin, and ConditionalLiteralPlugin.

Definition at line 683 of file PluginInterface.cpp.

void PluginInterface::processOptions	(	std::list< const char * > &	pluginOptions,
		ProgramCtx &	ctx
	)		`[virtual]`

Processes options for this plugin.

If you override this method, remove all options your plugin recognizes from pluginOptions. (Do not free the pointers, the const char* directly come from argv.) You can store configuration of your plugin using PluginData and ProgramCtx::getPluginData (see there for more information.)

Reimplemented in TestPlugin, QueryPlugin, ManualEvalHeuristicsPlugin, HigherOrderPlugin, StrongNegationPlugin, AggregatePlugin, FunctionPlugin, WeakConstraintPlugin, ChoicePlugin, and ConditionalLiteralPlugin.

Definition at line 691 of file PluginInterface.cpp.

virtual bool PluginInterface::providesCustomModelGeneratorFactory ( ProgramCtx & ctx ) const [inline, virtual]

Returns if this plugin provides a custom evaluation heuristics for a certain external atom.

Parameters:

Definition at line 431 of file PluginInterface.h.

void PluginInterface::setNameVersion	(	const std::string &	name,
		unsigned	major,
		unsigned	minor,
		unsigned	micro
	)		`[inline, protected]`

Set plugin name and version (informative, this is not the ABI version).

Set the version in your own constructor. It is recommended you add to configure.ac the line

   DLVHEX_DEFINE_VERSION([<YOURPLUGINNAME>],[$PACKAGE_VERSION])

and use for setNameVersion() the defines in config.h.in as created by configure (see also dlvhex.m4).

Definition at line 346 of file PluginInterface.h.

Referenced by AggregatePlugin::AggregatePlugin(), ChoicePlugin::ChoicePlugin(), ConditionalLiteralPlugin::ConditionalLiteralPlugin(), FunctionPlugin::FunctionPlugin(), HigherOrderPlugin::HigherOrderPlugin(), ManualEvalHeuristicsPlugin::ManualEvalHeuristicsPlugin(), QueryPlugin::QueryPlugin(), StrongNegationPlugin::StrongNegationPlugin(), and WeakConstraintPlugin::WeakConstraintPlugin().

virtual void PluginInterface::setupProgramCtx ( ProgramCtx & ) [inline, virtual]

Altering the ProgramCtx permits plugins to do many things, e.g., * installing model and finish callbacks * removing default model (and final) hooks * setting maxint * changing and configuring the solver backend to be used See internal plugins for example usage.

Reimplemented in TestPlugin, QueryPlugin, HigherOrderPlugin, StrongNegationPlugin, AggregatePlugin, FunctionPlugin, ChoicePlugin, ConditionalLiteralPlugin, and WeakConstraintPlugin.

Definition at line 483 of file PluginInterface.h.