#include <PrologEngine.h>

Inheritance diagram for knowrob::PrologEngine:

Collaboration diagram for knowrob::PrologEngine:

Public Types
using	ErrorHandler = ThreadPool::ExceptionHandler

using	GoalFactory = std::function< PrologTerm()>

using	Solution = std::map< Variable, TermPtr, std::less<> >

using	ErrorHandler = ThreadPool::ExceptionHandler

using	GoalFactory = std::function< PrologTerm()>

using	Solution = std::map< Variable, TermPtr, std::less<> >

Public Types inherited from knowrob::ThreadPool
using	ExceptionHandler = std::function< void(const std::exception &)>

using	ExceptionHandler = std::function< void(const std::exception &)>

Public Member Functions
	PrologEngine (uint32_t maxNumThreads=0)

	PrologEngine (uint32_t maxNumThreads=0)

Public Member Functions inherited from knowrob::ThreadPool
	ThreadPool (uint32_t maxNumThreads)

virtual	~ThreadPool ()

	ThreadPool (const ThreadPool &)=delete

void	shutdown ()

void	pushWork (const std::shared_ptr< ThreadPool::Runner > &goal, ThreadPool::ExceptionHandler exceptionHandler)

	ThreadPool (uint32_t maxNumThreads)

virtual	~ThreadPool ()

	ThreadPool (const ThreadPool &)=delete

void	shutdown ()

void	pushWork (const std::shared_ptr< ThreadPool::Runner > &goal, ThreadPool::ExceptionHandler exceptionHandler)

Static Public Member Functions
static void	initializeProlog ()

static void	finalizeProlog ()

static bool	isPrologInitialized ()

static bool	eval (const GoalFactory &goalFactory)

static std::optional< Solution >	oneSolution (const GoalFactory &goalFactory)

static std::vector< Solution >	allSolutions (const GoalFactory &goalFactory)

static void	query (const GoalFactory &goalFactory, const BindingsHandler &callback)

static bool	consult (const std::filesystem::path &uri, const char *module={})

static void	pushGoal (const std::shared_ptr< ThreadPool::Runner > &goal, const ErrorHandler &errHandler)

static void	pushGoalAndJoin (const std::shared_ptr< ThreadPool::Runner > &goal)

static std::filesystem::path	getPrologPath (const std::filesystem::path &filename)

static std::filesystem::path	getResourcePath (const std::filesystem::path &filename)

static void	initializeProlog ()

static void	finalizeProlog ()

static bool	isPrologInitialized ()

static bool	eval (const GoalFactory &goalFactory)

static std::optional< Solution >	oneSolution (const GoalFactory &goalFactory)

static std::vector< Solution >	allSolutions (const GoalFactory &goalFactory)

static void	query (const GoalFactory &goalFactory, const BindingsHandler &callback)

static bool	consult (const std::filesystem::path &uri, const char *module={})

static void	pushGoal (const std::shared_ptr< ThreadPool::Runner > &goal, const ErrorHandler &errHandler)

static void	pushGoalAndJoin (const std::shared_ptr< ThreadPool::Runner > &goal)

static std::filesystem::path	getPrologPath (const std::filesystem::path &filename)

static std::filesystem::path	getResourcePath (const std::filesystem::path &filename)

Protected Member Functions
bool	initializeWorker () override

bool	initializeWorker () override

Static Protected Member Functions
static void	expandSearchPaths ()

static void	expandSearchPaths ()

Static Protected Attributes
static bool	isPrologInitialized_ = false

static std::vector< std::string >	arguments_ = std::vector<std::string>()

static std::optional< PrologEngine >	self_ = std::nullopt

Additional Inherited Members
Protected Attributes inherited from knowrob::ThreadPool
std::function< void()>	finalizeWorker_

Detailed Description

A pool of threads with attached Prolog engines. Prolog threads have their own stacks and only share the Prolog heap: predicates, records, flags and other global non-backtrackable data. NOTE: term_t cannot be created in the main thread and used it in a worker thread! The term reference will be most likely a variable in the worker thread no matter what value it has in the main thread.

Definition at line 22 of file PrologEngine.h.

Member Typedef Documentation

◆ ErrorHandler [1/2]

using knowrob::PrologEngine::ErrorHandler = ThreadPool::ExceptionHandler

Definition at line 24 of file PrologEngine.h.

◆ ErrorHandler [2/2]

using knowrob::PrologEngine::ErrorHandler = ThreadPool::ExceptionHandler

Definition at line 24 of file PrologEngine.h.

◆ GoalFactory [1/2]

using knowrob::PrologEngine::GoalFactory = std::function<PrologTerm()>

Definition at line 25 of file PrologEngine.h.

◆ GoalFactory [2/2]

using knowrob::PrologEngine::GoalFactory = std::function<PrologTerm()>

Definition at line 25 of file PrologEngine.h.

◆ Solution [1/2]

using knowrob::PrologEngine::Solution = std::map<Variable, TermPtr, std::less<> >

Definition at line 26 of file PrologEngine.h.

◆ Solution [2/2]

using knowrob::PrologEngine::Solution = std::map<Variable, TermPtr, std::less<> >

Definition at line 26 of file PrologEngine.h.

Constructor & Destructor Documentation

◆ PrologEngine() [1/2]

PrologEngine::PrologEngine ( uint32_t maxNumThreads = 0 )

explicit

Parameters

maxNumThreads maximum number of worker threads.

Definition at line 32 of file PrologEngine.cpp.

         : ThreadPool(maxNumThreads) {
     finalizeWorker_ = [] {
         // destroy the engine previously bound to this thread
         PL_thread_destroy_engine();
         KB_DEBUG("destroyed Prolog engine");
     };
     initializeProlog();
 }

◆ PrologEngine() [2/2]

knowrob::PrologEngine::PrologEngine ( uint32_t maxNumThreads = 0 )

explicit

Parameters

maxNumThreads maximum number of worker threads.

Member Function Documentation

◆ allSolutions() [1/2]

std::vector< PrologEngine::Solution > PrologEngine::allSolutions ( const GoalFactory & goalFactory )

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory a goal factory

Returns: all solutions found

Definition at line 224 of file PrologEngine.cpp.

                                                                                          {
     std::vector<Solution> solutions;
  
     pushGoalAndJoin(std::make_shared<LambdaRunner>(
             [&goalFactory, &solutions](const LambdaRunner::StopChecker &hasStopRequest) {
                 auto goal = goalFactory();
                 auto qid = goal.openQuery(prologQueryFlags);
                 while (!hasStopRequest() && goal.nextSolution(qid)) {
                     Solution solution;
                     for (auto &var: goal.vars()) {
                         solution[var.first] = PrologTerm::toKnowRobTerm(var.second);
                     }
                     solutions.push_back(solution);
                 }
                 PL_close_query(qid);
             }));
  
     return solutions;
 }

◆ allSolutions() [2/2]

static std::vector<Solution> knowrob::PrologEngine::allSolutions ( const GoalFactory & goalFactory )

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory a goal factory

Returns: all solutions found

◆ consult() [1/2]

bool PrologEngine::consult	(	const std::filesystem::path &	uri,
		const char *	module = `{}`
	)

static

Consults a Prolog file, i.e. loads facts and rules and executed directives in the file. May throw an exception if there is no valid Prolog file at the given path.

Parameters

uri	the local path to the file.
module	the module to consult the file into

Returns: true on success

Definition at line 264 of file PrologEngine.cpp.

                                                                            {
     static auto consult_f = "consult";
     auto path = PrologEngine::getPrologPath(uri);
  
     return PrologEngine::eval([&]() {
         PrologTerm plTerm(consult_f, path.native());
         if (module) plTerm.setModule(module);
         return plTerm;
     });
 }

◆ consult() [2/2]

static bool knowrob::PrologEngine::consult	(	const std::filesystem::path &	uri,
		const char *	module = `{}`
	)

static

Consults a Prolog file, i.e. loads facts and rules and executed directives in the file. May throw an exception if there is no valid Prolog file at the given path.

Parameters

uri	the local path to the file.
module	the module to consult the file into

Returns: true on success

◆ eval() [1/2]

bool PrologEngine::eval ( const GoalFactory & goalFactory )

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory a goal factory

Returns: true if the goal succeeded

Definition at line 191 of file PrologEngine.cpp.

                                                       {
     bool hasSolution = false;
  
     pushGoalAndJoin(std::make_shared<LambdaRunner>(
             [&goalFactory, &hasSolution](const LambdaRunner::StopChecker &) {
                 auto goal = goalFactory();
                 auto qid = goal.openQuery(prologQueryFlags);
                 hasSolution = goal.nextSolution(qid);
                 PL_close_query(qid);
             }));
  
     return hasSolution;
 }

◆ eval() [2/2]

static bool knowrob::PrologEngine::eval ( const GoalFactory & goalFactory )

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory a goal factory

Returns: true if the goal succeeded

◆ expandSearchPaths() [1/2]

void PrologEngine::expandSearchPaths ( )

staticprotected

Definition at line 130 of file PrologEngine.cpp.

                                      {
     static std::filesystem::path projectPath(KNOWROB_SOURCE_DIR);
     static std::filesystem::path installPath(KNOWROB_INSTALL_PREFIX);
  
     // expand library search path, e.g. used by use_module/2 to locate Prolog source files.
     // prefer files from projectPath
     auto libPaths = {
             installPath / "share" / "knowrob" / "integration" / "prolog",
             installPath / "share" / "knowrob" / "reasoner" / "prolog",
             installPath / "share" / "knowrob" / "reasoner",
             installPath / "share" / "knowrob",
             projectPath / "src" / "integration" / "prolog",
             projectPath / "src" / "reasoner" / "prolog",
             projectPath / "src" / "reasoner",
             projectPath / "src"
     };
     for (const auto &p: libPaths) {
         if (!exists(p)) continue;
         eval([&p] {
             return PrologTerm("asserta", PrologTerm(":", "user", PrologTerm("library_directory", p.string())));
         });
     }
  
     // expand file search path, e.g. used by absolute_file_name/3 predicate
     // "knowrob" files:
     auto filePaths_knowrob = {
             projectPath,
             installPath / "share" / "knowrob"
     };
     for (const auto &p: filePaths_knowrob) {
         if (!exists(p)) continue;
         eval([&p] {
             return PrologTerm("assertz", PrologTerm("file_search_path", "knowrob", p.string()));
         });
     }
  
     // "test" files:
     auto filePaths_tests = {
             projectPath / "tests"
     };
     for (const auto &p: filePaths_tests) {
         if (!exists(p)) continue;
         eval([&p] {
             return PrologTerm("assertz", PrologTerm("file_search_path", "test", p.string()));
         });
     }
 }

◆ expandSearchPaths() [2/2]

static void knowrob::PrologEngine::expandSearchPaths ( )

staticprotected

◆ finalizeProlog() [1/2]

void PrologEngine::finalizeProlog ( )

static

Must be called after all Prolog library interactions.

Definition at line 118 of file PrologEngine.cpp.

                                   {
     if (!isPrologInitialized_) return;
     // finalize the Prolog engine
     self_->shutdown();
     PL_cleanup(0);
     arguments_.clear();
     self_ = std::nullopt;
     // toggle off flag
     isPrologInitialized_ = false;
     KB_DEBUG("Prolog has been finalized.");
 }

◆ finalizeProlog() [2/2]

static void knowrob::PrologEngine::finalizeProlog ( )

static

Must be called after all Prolog library interactions.

◆ getPrologPath() [1/2]

std::filesystem::path PrologEngine::getPrologPath ( const std::filesystem::path & filename )

static

Resolve the path to a Prolog file. The function attempts to resolve project-relative paths.

Parameters

filename a name or path.

Returns: a path where the file might be stored

Definition at line 275 of file PrologEngine.cpp.

                                                                                {
     static std::filesystem::path projectPath(KNOWROB_SOURCE_DIR);
     static std::filesystem::path installPath(KNOWROB_INSTALL_PREFIX);
  
     if (!exists(filePath)) {
         auto possiblePaths = {
                 projectPath / filePath,
                 projectPath / "src" / filePath,
                 projectPath / "src" / "reasoner" / "prolog" / filePath,
                 installPath / "share" / "knowrob" / filePath
         };
         for (const auto &p: possiblePaths) {
             if (exists(p)) return p;
         }
     }
     return filePath;
 }

◆ getPrologPath() [2/2]

static std::filesystem::path knowrob::PrologEngine::getPrologPath ( const std::filesystem::path & filename )

static

Resolve the path to a Prolog file. The function attempts to resolve project-relative paths.

Parameters

filename a name or path.

Returns: a path where the file might be stored

◆ getResourcePath() [1/2]

std::filesystem::path PrologEngine::getResourcePath ( const std::filesystem::path & filename )

static

Resolve the path to a resource file. The function attempts to resolve project-relative paths.

Parameters

filename a name or path.

Returns: a path where the file might be stored

Definition at line 293 of file PrologEngine.cpp.

                                                                                  {
     static std::filesystem::path projectPath(KNOWROB_SOURCE_DIR);
     static std::filesystem::path installPath(KNOWROB_INSTALL_PREFIX);
  
     if (!exists(filePath)) {
         auto possiblePaths = {
                 projectPath / filePath,
                 installPath / "share" / "knowrob" / filePath
         };
         for (const auto &p: possiblePaths) {
             if (exists(p)) return p;
         }
     }
     return filePath;
 }

◆ getResourcePath() [2/2]

static std::filesystem::path knowrob::PrologEngine::getResourcePath ( const std::filesystem::path & filename )

static

Resolve the path to a resource file. The function attempts to resolve project-relative paths.

Parameters

filename a name or path.

Returns: a path where the file might be stored

◆ initializeProlog() [1/2]

void PrologEngine::initializeProlog ( )

static

Must be called before any Prolog library interactions.

Definition at line 72 of file PrologEngine.cpp.

                                     {
     if (isPrologInitialized_) return;
     // toggle on flag
     isPrologInitialized_ = true;
  
     // PL_initialise changes the locale. This can have bad consequences.
     // I experienced unit tests for Redland failing because of this!
     // Seems like it is related to parsing of numbers. Setting
     // LC_NUMERIC to "C" before PL_initialise seems to fix the problem.
     setenv("LC_NUMERIC", "C", 1);
  
     int pl_ac = 0;
     char *pl_av[5];
     arguments_.resize(4);
     arguments_[pl_ac++] = getNameOfExecutable();
     // '-g true' is used to suppress the welcome message
     arguments_[pl_ac++] = "-g";
     arguments_[pl_ac++] = "true";
     // Inhibit any signal handling by Prolog
     arguments_[pl_ac++] = "--signals=false";
     for (int i = 0; i < pl_ac; i++) {
         pl_av[i] = (char *) arguments_[i].c_str();
     }
     PL_initialise(pl_ac, pl_av);
     KB_DEBUG("Prolog has been initialized.");
     self_.emplace(std::thread::hardware_concurrency());
  
     // expand the Prolog library_directory path used to locate Prolog files
     expandSearchPaths();
  
     // register some foreign predicates, i.e. cpp functions that are used to evaluate predicates.
     // note: the predicates are loaded into module "user"
     PL_register_foreign("knowrob_register_namespace",
                         2, (pl_function_t) pl_rdf_register_namespace2, 0);
     PL_register_foreign("url_resolve",
                         2, (pl_function_t) url_resolve2, 0);
     PL_register_foreign("log_message", 2, (pl_function_t) prolog::log_message2, 0);
     PL_register_foreign("log_message", 4, (pl_function_t) prolog::log_message4, 0);
     PL_register_extensions_in_module("algebra", prolog::PL_extension_algebra);
     PL_register_extensions_in_module("semweb", prolog::PL_extension_semweb);
     KB_DEBUG("common foreign Prolog modules have been registered.");
  
     consult(std::filesystem::path("integration") / "prolog" / "__init__.pl", "user");
     KB_DEBUG("KnowRob __init__.pl has been consulted.");
 }

◆ initializeProlog() [2/2]

static void knowrob::PrologEngine::initializeProlog ( )

static

Must be called before any Prolog library interactions.

◆ initializeWorker() [1/2]

bool PrologEngine::initializeWorker ( )

overrideprotectedvirtual

Reimplemented from knowrob::ThreadPool.

Definition at line 42 of file PrologEngine.cpp.

                                     {
     // call PL_thread_attach_engine once initially for each worker thread
     if (PL_thread_attach_engine(nullptr) < 0) {
         // `-1` indicates an error, and `-2` that Prolog is compiled without multithreading support
         KB_ERROR("Failed to attach Prolog engine to current thread!");
         return false;
     } else {
         // if PL_thread_attach_engine()>0, then the Prolog ID for the thread was returned
         KB_DEBUG("Attached Prolog engine to current thread.");
         return true;
     }
 }

◆ initializeWorker() [2/2]

bool knowrob::PrologEngine::initializeWorker ( )

overrideprotectedvirtual

Reimplemented from knowrob::ThreadPool.

◆ isPrologInitialized() [1/2]

static bool knowrob::PrologEngine::isPrologInitialized ( )

inlinestatic

Returns: true if the Prolog engine is initialized

Definition at line 46 of file PrologEngine.h.

46 { return isPrologInitialized_; }

◆ isPrologInitialized() [2/2]

static bool knowrob::PrologEngine::isPrologInitialized ( )

inlinestatic

Returns: true if the Prolog engine is initialized

Definition at line 46 of file PrologEngine.h.

46 { return isPrologInitialized_; }

◆ oneSolution() [1/2]

std::optional< PrologEngine::Solution > PrologEngine::oneSolution ( const GoalFactory & goalFactory )

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory a goal factory

Returns: the first solution found or an empty optional

Definition at line 205 of file PrologEngine.cpp.

                                                                                           {
     std::optional<Solution> solution;
  
     pushGoalAndJoin(std::make_shared<LambdaRunner>(
             [&goalFactory, &solution](const LambdaRunner::StopChecker &) {
                 auto goal = goalFactory();
                 auto qid = goal.openQuery(prologQueryFlags);
                 if (goal.nextSolution(qid)) {
                     solution = Solution();
                     for (auto &var: goal.vars()) {
                         solution.value()[var.first] = PrologTerm::toKnowRobTerm(var.second);
                     }
                 }
                 PL_close_query(qid);
             }));
  
     return solution;
 }

◆ oneSolution() [2/2]

static std::optional<Solution> knowrob::PrologEngine::oneSolution ( const GoalFactory & goalFactory )

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory a goal factory

Returns: the first solution found or an empty optional

◆ pushGoal() [1/2]

void PrologEngine::pushGoal	(	const std::shared_ptr< ThreadPool::Runner > &	goal,
		const ErrorHandler &	errHandler
	)

static

Run a goal in a worker thread with a Prolog engine.

Parameters

goal	the work goal
errHandler	a function that handles exceptions thrown by the goal

Definition at line 178 of file PrologEngine.cpp.

                                                                                                        {
     self_->pushWork(goal, errHandler);
 }

◆ pushGoal() [2/2]

static void knowrob::PrologEngine::pushGoal	(	const std::shared_ptr< ThreadPool::Runner > &	goal,
		const ErrorHandler &	errHandler
	)

static

Run a goal in a worker thread with a Prolog engine.

Parameters

goal	the work goal
errHandler	a function that handles exceptions thrown by the goal

◆ pushGoalAndJoin() [1/2]

void PrologEngine::pushGoalAndJoin ( const std::shared_ptr< ThreadPool::Runner > & goal )

static

Run a goal in a worker thread with a Prolog engine and wait for termination. Also rethrow any exceptions in the thread of the caller.

Parameters

goal	the work goal

Definition at line 182 of file PrologEngine.cpp.

                                                                               {
     // push goal and wait for termination
     std::exception_ptr excPtr = nullptr;
     pushGoal(goal, [&excPtr](...) { excPtr = std::current_exception(); });
     goal->join();
     // rethrow any exceptions in this thread
     if (excPtr) std::rethrow_exception(excPtr);
 }

◆ pushGoalAndJoin() [2/2]

static void knowrob::PrologEngine::pushGoalAndJoin ( const std::shared_ptr< ThreadPool::Runner > & goal )

static

Run a goal in a worker thread with a Prolog engine and wait for termination. Also rethrow any exceptions in the thread of the caller.

Parameters

goal	the work goal

◆ query() [1/2]

void PrologEngine::query	(	const GoalFactory &	goalFactory,
		const BindingsHandler &	callback
	)

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory	a goal factory
callback	a function that handles the solutions

Definition at line 244 of file PrologEngine.cpp.

                                                                                         {
     pushGoalAndJoin(std::make_shared<LambdaRunner>(
             [&goalFactory, &callback](const LambdaRunner::StopChecker &hasStopRequest) {
                 auto goal = goalFactory();
                 auto qid = goal.openQuery(prologQueryFlags);
                 while (!hasStopRequest() && goal.nextSolution(qid)) {
                     auto bindings = std::make_shared<Bindings>();
                     for (auto &var: goal.vars()) {
                         if (PL_term_type(var.second) == PL_VARIABLE) {
                             continue;
                         }
                         bindings->set(std::make_shared<Variable>(var.first),
                                       PrologTerm::toKnowRobTerm(var.second));
                     }
                     callback(bindings);
                 }
                 PL_close_query(qid);
             }));
 }

◆ query() [2/2]

static void knowrob::PrologEngine::query	(	const GoalFactory &	goalFactory,
		const BindingsHandler &	callback
	)

static

Evaluate a goal in a thread with a Prolog engine.

Parameters

goalFactory	a goal factory
callback	a function that handles the solutions

Member Data Documentation

◆ arguments_

std::vector< std::string > PrologEngine::arguments_ = std::vector<std::string>()

staticprotected

Definition at line 118 of file PrologEngine.h.

◆ isPrologInitialized_

bool PrologEngine::isPrologInitialized_ = false

staticprotected

Definition at line 117 of file PrologEngine.h.

◆ self_

std::optional< PrologEngine > PrologEngine::self_ = std::nullopt

staticprotected

Definition at line 119 of file PrologEngine.h.

The documentation for this class was generated from the following files:

build/_CPack_Packages/Linux/DEB/knowrob-2.1.0-Linux/usr/include/knowrob/integration/prolog/PrologEngine.h
src/integration/prolog/PrologEngine.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Static Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ErrorHandler [1/2]

◆ ErrorHandler [2/2]

◆ GoalFactory [1/2]

◆ GoalFactory [2/2]

◆ Solution [1/2]

◆ Solution [2/2]

Constructor & Destructor Documentation

◆ PrologEngine() [1/2]

◆ PrologEngine() [2/2]

Member Function Documentation

◆ allSolutions() [1/2]

◆ allSolutions() [2/2]

◆ consult() [1/2]

◆ consult() [2/2]

◆ eval() [1/2]

◆ eval() [2/2]

◆ expandSearchPaths() [1/2]

◆ expandSearchPaths() [2/2]

◆ finalizeProlog() [1/2]

◆ finalizeProlog() [2/2]

◆ getPrologPath() [1/2]

◆ getPrologPath() [2/2]

◆ getResourcePath() [1/2]

◆ getResourcePath() [2/2]

◆ initializeProlog() [1/2]

◆ initializeProlog() [2/2]

◆ initializeWorker() [1/2]

◆ initializeWorker() [2/2]

◆ isPrologInitialized() [1/2]

◆ isPrologInitialized() [2/2]

◆ oneSolution() [1/2]

◆ oneSolution() [2/2]

◆ pushGoal() [1/2]

◆ pushGoal() [2/2]

◆ pushGoalAndJoin() [1/2]

◆ pushGoalAndJoin() [2/2]

◆ query() [1/2]

◆ query() [2/2]

Member Data Documentation

◆ arguments_

◆ isPrologInitialized_

◆ self_