PythonEval.h

Go to the documentation of this file.

/*
 * @file opencog/cython/PythonEval.h
 *
 * Simple python expression evaluator.
 *
 * @author Zhenhua Cai <czhedu@gmail.com>
 *         Ramin Barati <rekino@gmail.com>
 *         Keyvan Mir Mohammad Sadeghi <keyvan@opencog.org>
 *         Curtis Faith <curtis.m.faith@gmail.com>
 * @date   2011-09-20
 *
 * @Note
 *   Zhenhua: Many code are copied directly from original /opencog/cython/PythonModule.h|cc
 *            by Joel. I also borrowed some ideas from SchemeEval.h|cc
 *
 *   Ramin: This class is completely revised by me and Keyvan. The new code is inspired
 *          by Linas' SchemeEval and borrowed some ideas from Joel's PythonModule.
 *
 *  @todo
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License v3 as
 * published by the Free Software Foundation and including the exceptions
 * at http://opencog.org/wiki/Licenses
 *
 * 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 Affero General Public License
 * along with this program; if not, write to:
 * Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef OPENCOG_PYTHON_EVAL_H
#define OPENCOG_PYTHON_EVAL_H
#ifdef HAVE_CYTHON

#include "PyIncludeWrapper.h"

#include <map>
#include <mutex>
#include <string>
#include <vector>

#include <boost/filesystem/operations.hpp>

#include <opencog/atomspace/Handle.h>
#include <opencog/atomspace/TruthValue.h>
#include <opencog/shell/GenericEval.h>


namespace opencog {

class AtomSpace;
class CogServer;

class PythonThreadLocker
{
    private:
        PyGILState_STATE state;

    public:
        PythonThreadLocker() : state(PyGILState_Ensure())
        {}

        ~PythonThreadLocker() {
            PyGILState_Release(state);
        }
};

class PythonEval : public GenericEval
{
    private:
        void initialize_python_objects_and_imports(void);

        // Module utility functions
        void import_module( const boost::filesystem::path &file,
                            PyObject* pyFromList);
        void add_module_directory(const boost::filesystem::path &directory);
        void add_module_file(const boost::filesystem::path &file);
        void add_modules_from_path(std::string path);
        void add_modules_from_abspath(std::string path);

        // Python utility functions
        PyObject* call_user_function(const std::string& func,
                                     Handle varargs);
        void build_python_error_message(const char* function_name,
                                        std::string& errorMessage);
        void add_to_sys_path(std::string path);
        PyObject * atomspace_py_object(AtomSpace *);
        void print_dictionary(PyObject*);
        void execute_string(const char* command);
        int argument_count(PyObject* pyFunction);
        PyObject* module_for_function(const std::string& moduleFunction,
                                      std::string& functionName);

        static PythonEval* singletonInstance;

        AtomSpace* _atomspace;
        // Resource Acquisition is Allocation, for the current AtomSpace.
        // If anything throws an exception, then dtor runs and restores
        // the old atomspace.
        struct RAII {
            RAII(PythonEval* pev, AtomSpace* as) : _pev(pev)
               { _save_as = pev->_atomspace; pev->_atomspace = as; }
            ~RAII() {_pev->_atomspace = _save_as; }
            AtomSpace* _save_as;
            PythonEval* _pev;
        };

        // Single, global mutex for serializing access to the atomspace.
        // The singleton-instance design of this class forces us to
        // serialize access (the GIL is not enough), because there is
        // no way to guarantee that python won't accidentally be called
        // from multiple threads.  That's because the EvaluationLink
        // is called from scheme and from the pattern matcher, and its
        // unknown how many threads those things might be running in.
        // The lock is recursive, because we may need to use multiple
        // different atomspaces with the evaluator, in some nested
        // fashion. So this lock prevents other threads from using the
        // wrong atomspace in some other thread.  Unfort
        static std::recursive_mutex _mtx;

        PyObject* _pyGlobal;
        PyObject* _pyLocal;
        PyObject* _pyRootModule;

        PyObject* _pySysPath;

        std::map <std::string, PyObject*> _modules;

        std::string _result;
        int _paren_count;

    public:
        PythonEval(AtomSpace*);
        ~PythonEval();

        static void create_singleton_instance(AtomSpace*);

        static void delete_singleton_instance();

        static PythonEval & instance(AtomSpace* atomspace = NULL);

        // The async-output interface.
        virtual void begin_eval() {}
        virtual void eval_expr(const std::string&);
        virtual std::string poll_result();

        // The synchronous-output interface.
        std::string eval(const std::string& expr)
            { begin_eval(); eval_expr(expr); return poll_result(); }

        std::string apply_script(const std::string& script);

        Handle apply(AtomSpace*, const std::string& func, Handle varargs);

        TruthValuePtr apply_tv(AtomSpace*, const std::string& func, Handle varargs);

        void print_root_dictionary()
            { this->print_dictionary(PyModule_GetDict(_pyRootModule)); }

};

void global_python_initialize();

void global_python_finalize();

} /* namespace opencog */

#endif /* HAVE_CYTHON */
#endif /* OPENCOG_PYTHON_EVAL_H */