Classes
class	BindingLogicError
	Python throws this exception when an issue expected to be detectable in the code happens at run time. More...

class	BindingRuntimeError
	Python throws this exception when an issue not detectable in the code happens at run time. More...

class	ObjectHandler
	Handler of CPython object pointers used by Python to handle references counts. More...

class	ObjectHandlersCollection
	Collection of ObjectHandler used internally by Python. More...

Typedefs
using	PathEntriesList = std::vector< std::string >
	Path, as a vector of strings.

using	ObjectHandlersList = std::vector< ObjectHandler >
	Parameters list to pass to `call()` or to functions that create collections.

using	ObjectPointer = PyObject *
	Pointer to scope objects (either imported modules or instances of a class) or callable objects (functions or methods). More...

using	RawCode = std::string
	Plain Python code.

using	Program = std::vector< RawCode >
	Complete program. More...

Functions
bool	isInitialized ()
	Check whether Python is initialized. More...

void	init (std::string const &programName, PathEntriesList const &pythonSysPath=PathEntriesList())
	Initializes Python. More...

void	shutdown ()
	Shuts down Python. More...

void	execute (RawCode const &code)
	Executes raw code. More...

void	execute (Program const &program)
	Executes a program. More...

ObjectPointer	import (std::string const &moduleName)
	Imports a module by its name. More...

ObjectPointer	module (std::string const &moduleName)
	Retrieves a previously imported module. More...

ObjectHandler const &	object (ObjectPointer scope, std::string const &objectName)
	Retrieves an object by its name from a scope pointer. More...

ObjectHandler const &	object (std::string const &moduleName, std::string const &objectName)
	Retrieves an object by its name from a module name. More...

ObjectPointer	callable (ObjectPointer scope, std::string const &callableName, bool forceReload=false)
	Retrieves a callable object (function or method) by its name from a scope pointer. More...

ObjectPointer	callable (std::string const &moduleName, std::string const &callableName, bool forceReload=false)
	Retrieves a callable object (function) by its name from a module name. More...

ObjectHandler const &	call (ObjectPointer callableObject, ObjectHandlersList const &args={}, bool keepArguments=false)
	Calls a callable with the given arguments. More...

ObjectHandler	tuple (ObjectHandlersList const &args={}, bool keepArguments=false)
	Creates a tuple object initialized with the given arguments. More...

ObjectHandler	list (ObjectHandlersList const &args={}, bool keepArguments=false)
	Creates a list object initialized with the given arguments. More...

void	addList (ObjectHandler list, ObjectHandler item, bool keepArg=false)
	Adds an item to the end of a list. More...

ObjectHandler	fromAscii (std::string const &str)
	Converts a string to a UTF-8 CPython string object. More...

std::string	toAscii (ObjectHandler utfStr, bool keepArg=false)
	Converts a UTF-8 CPython string object to a std::string. More...

ObjectHandler const &	keepArgument (ObjectHandler const &object)
	Prevents an object reference from being stolen. More...

ObjectHandler const &	controlArgument (ObjectHandler object)
	Places an CPython object under control of Python. More...

void	forgetArgument (ObjectHandler const &object)
	Get rid of a reference of an object under control. More...

void	beginCriticalSection ()
	Enters a critical section, preventing other threads from entering any Python critical section. More...

void	endCriticalSection ()
	Exits a critical section, allowing other threads to enter a Python critical section. More...

bool	operator== (ObjectHandler const &lhs, ObjectHandler const &rhs)
	Equality operator. More...

bool	operator!= (ObjectHandler const &lhs, ObjectHandler const &rhs)
	Inequality operator. More...

Variables
const std::string	moduleMain
	Main module ("__main__"). More...

const std::string	moduleBuiltins
	Built-ins module ("builtins"). More...

Detailed Description

Helper classes and functions wrapping the CPython standard API.

Not all functions of the CPython API are wrapped here. shlublu::Python is intended to make the most common operations simpler without preventing users from using advanced features from the CPython API when needed. In particular, this module focuses of making the references count handling simpler and less error-prone than doing it manually as CPython requires.

Requirements
This module uses the official Python3.x library. Client programs need their include path, libraries path and linker input to be updated as follows:

Include path: <depends on your local installation>
Libraries path: <depends on your local installation>
Library file:
- Linux: libpython3.<x>m.a
- Windows: python3<x>.dll

Typical examples of use

Should you just need to execute some code with the CPython Interpreter:
#include <iostream>

#include <vector>

#include <shlublu/binding/Python.h>

#include <shlublu/text/String.h>

using namespace shlublu;

int main(int, char* argv[])

{

int retCode(0);

try

{

const int x(5);

const double y(2.0);

// Initializes the Python Interpreter and gives it the name of this program.

Python::init(*argv);

// Writes a function: sum(x,y) -> x + y, then prints the result of a call

Python::execute("def sum(x, y):\n\treturn x + y");

Python::execute("print('Sum: ' + repr(sum(" + String::xtos(x) + "," + String::xtos(y) + ")))");

// Instructions can also be executed as a program

const Python::Program program({ "import math", "print('Factorial: ' + repr(math.factorial(" + String::xtos(x) + ")))" });

Python::execute(program);

Python::shutdown(); // optional: this will be called atexit() anyway

}

catch (std::exception const& e)

{

std::cerr << "ERROR: " << e.what() << std::endl;

retCode = -1;

}

return retCode;

}
Should you need your program to interact more deeply with the CPython Interpreter:
#include <iostream>

#include <vector>

#include <shlublu/binding/Python.h>

#include <shlublu/text/String.h>

using namespace shlublu;

int main(int, char* argv[])

{

int retCode(0);

try

{

const double x(5);

const int y(2);

Python::init(*argv);

// Imports math and keeps a pointer on it for later

const auto math(Python::import("math"));

// Calls 'math.pow(y, x)' using Python and some CPython functions it would have been pointless to wrap. Keeps the result as a Python object called 'xPowY'

const auto xPowY

(

Python::call

(

Python::callable(math, "pow"), // takes a pointer to math.pow

{ PyFloat_FromDouble(x), PyLong_FromLong(y) } // passes arguments obtained from CPython calls

)

);

// Python::call() has decreased the references counts of the arguments for you. You would have had to do it manually otherwise.

// Should you need to keep them for later there are ways. This is explained later in this page.

// Prints the result using std::iostream and CPython

std::cout << "pow(" << x << ", " << y << "): " << PyFloat_AsDouble(xPowY) << std::endl; // displays "pow(5, 2): 25"

// Now let's compute and print the square root of this result using the interpreter (this displays "5.0")

Python::call

(

Python::callable(Python::moduleBuiltins, "print"), // takes a pointer to the Python built-in 'print' function

{

Python::call

(

Python::callable("math", "sqrt"), // this shows that keeping a pointer on imports is not mandatory. Using names is ok too as long as the import has been done.

{ xPowY } // passes the result of the previous call to 'pow' as an argument to 'sqrt'

)

}

);

// Python::shutdown() will be called atexit(). This will take care of decreasing all needed references counts for you (modules, functions, arguments, results, etc).

// There are ways to do some cleanup manually should memory be an issue. This is explained later in this page.

}

catch (std::exception const& e)

{

std::cerr << "ERROR: " << e.what() << std::endl;

retCode = -1;

}

return retCode;

}
More advanced features are explained below.

Attention

About concurrency
The CPython interpreter is global and shared by all the threads of the process. So is its memory state, including imports and objects.
All functions of this module are thread-safe. However,

groups of Python calls that constitute transactions in your C++ code should be surrounded by beginCriticalSection() / endCriticalSection() to prevent other threads from calling the CPython interpreter while these transactions are executing. Such interruptions would not crash the program but could make the results inconsistents should these threads work on the same shared pieces of data.
calls to CPython functions that access to objects should also be surrounded by beginCriticalSection() / endCriticalSection() as these functions do not support concurrency. For example, PyLong_FromLong(42), Py_XDECREF(object), or PyLong_AsLong(object) fall in this category.

Should you need more isolation, you can use the CPython API to setup multiple interpreters knowing that there are caveats described in the documentation. One of this limitation is the use of the PyGILState_*() API. As shlublu::Python doesn't use this API there should not be any issue there.

Forking is ok as the child process receives a full copy of the memory of the parent process made at fork() time. Testing shows the interpreter supports this very well, providing a full isolation, as long as the fork operation is conducted from a mono-thread process. Should you wish to fork a multi-threads process there are some cautions.

Typedef Documentation

◆ ObjectPointer

using shlublu::Python::ObjectPointer = typedef PyObject*

Pointer to scope objects (either imported modules or instances of a class) or callable objects (functions or methods).

Conversion from and to ObjectHandler is silent.

◆ Program

using shlublu::Python::Program = typedef std::vector<RawCode>

Complete program.

Typical use is one line per element. Indentation is under the responsability of the programmer.

Function Documentation

◆ isInitialized()

bool shlublu::Python::isInitialized ( )

Check whether Python is initialized.

Calling shutdown() makes Python not to be initialized anymore.

Returns: the initialization status

◆ init()

void shlublu::Python::init	(	std::string const &	programName,
		PathEntriesList const &	pythonSysPath = `PathEntriesList()`
	)

Initializes Python.

Should pythonSysPath differ between two calls not separated by a shutdown(), elements of the second path that are not part of the first are appended.

This function can be called several times in a row with no issue.

Parameters

programName	the name to give the interpreter. The `argv[0]` argument given to the `main()` function of your program is a preferred choice though not mandatory (see below)
pythonSysPath	system path that will be appended to `sys.path` if not already part of it

See also: Py_SetProgramName()

◆ shutdown()

void shlublu::Python::shutdown ( )

Shuts down Python.

Cleans up all references to the various objects previously handled or created by using Python and calls Py_Finalize().

This function can be called several times in a row with no issue even if Python has not been initialized in the first place. It is called through atexit(), which makes its explicit use optional.

See also: Py_Finalize(); atexit()

◆ execute() [1/2]

void shlublu::Python::execute ( RawCode const & code )

Executes raw code.

Parameters

code	piece of code to execute. Lines should be separated by `\n`. Intentation should be materialized by spaces or `\t`.

Exceptions

BindingLogicError if Python is not initialized or if the piece of code causes an error at interpretation time.

Example

Python::execute("print('text to print')"); // prints "text to print"

◆ execute() [2/2]

void shlublu::Python::execute ( Program const & program )

Executes a program.

The whole program is executed in a row and cannot be interrupted by other threads using the CPython interpreter.

Parameters

program code to execute, typically splitted by lines. Intentation should be materialized by spaces or \t. Empty lines are permitted.

Exceptions

BindingLogicError if Python is not initialized or if any line of code causes an error at interpretation time.

Example

Python::execute({ "def testFunc(x):", "\tprint(x + ' is now printed')", "testFunc('text to print')" }); // prints "text to print is now printed"

◆ import()

ObjectPointer shlublu::Python::import ( std::string const & moduleName )

Imports a module by its name.

Modules can be imported several times in a row with no issue, the same pointer being returned each time.

The returned pointer is under control of Python for garbage collection at shutdown() time only.

Parameters

moduleName the name of the module, dot-delimited should it be part of a package

Returns: a pointer to the imported module

Exceptions

BindingLogicError if Python is not initialized or if the module cannot be found

Example

const auto pathModule(Python::import("os.path"));

◆ module()

ObjectPointer shlublu::Python::module ( std::string const & moduleName )

Retrieves a previously imported module.

Modules have to be imported by import() to be retrieved that way. Modules imported by execute() (as execute("import <name>")) are not retrieved by this function.

The returned pointer is under control of Python for garbage collection at shutdown() time only.

Parameters

moduleName the name of the module, dot-delimited should it be part of a package

Returns: a pointer to the module

Exceptions

BindingLogicError if Python is not initialized or if the module has not be previsouly imported by import()

Example

Python::import("os.path")

const auto pathModule(Python::retrieve("os.path"));

◆ object() [1/2]

ObjectHandler const& shlublu::Python::object	(	ObjectPointer	scope,
		std::string const &	objectName
	)

Retrieves an object by its name from a scope pointer.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

scope	pointer to the module, namespace or object the object to retrieve belongs to
objectName	the name of the object to retrieve

Returns: a handler of the retrieved object

Exceptions

BindingLogicError if Python is not initialized or if the object cannot be found

Example

Python::execute(Python::Program({ "import fractions as f", "fraction = f.Fraction(3, 2)" }));
 
const auto fraction(Python::object(Python::moduleMain, "fraction"));
const auto denominator(Python::object(fraction, "denominator"));
 
std::cout << String::xtos(PyLong_AsLong(denominator)) << std::endl;

◆ object() [2/2]

ObjectHandler const& shlublu::Python::object	(	std::string const &	moduleName,
		std::string const &	objectName
	)

Retrieves an object by its name from a module name.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

moduleName	the name of the module the object to retrieve belongs to
objectName	the name of the object to retrieve

Returns: a handler of the retrieved object

Exceptions

BindingLogicError if Python is not initialized, if the module has not been imported by import(), or if the object cannot be found

Example

Python::execute(Python::Program({ "import fractions as f", "fraction = f.Fraction(3, 2)"}));
 
const auto fraction(Python::object(Python::moduleMain, "fraction"));

◆ callable() [1/2]

ObjectPointer shlublu::Python::callable	(	ObjectPointer	scope,
		std::string const &	callableName,
		bool	forceReload = `false`
	)

Retrieves a callable object (function or method) by its name from a scope pointer.

Callable objects are less likely to change than non-callable objects during the execution of the program. For this reason, pointers to callable are memorized. Multiple calls to this function with the same scope argument and callable name make the pointer retrieved in the first place to be returned, unless forceReload is set to true.

The returned pointer is under control of Python for garbage collection at shutdown() time only.

Parameters

scope	pointer to the module, namespace or object the callable object to retrieve belongs to
callableName	the name of the callable object to retrieve
forceReload	if true, refresh the callable object pointer before returning it and dispose of any previous version

Returns: a pointer to the retrieved callable object

Exceptions

BindingLogicError if Python is not initialized, if the object cannot be found or if it is not callable

Example

const auto mathModule(Python::import("math"));
const auto fabs(Python::callable(mathModule, "fabs"));
 
std::cout << PyFloat_AsDouble(Python::call(fabs, { PyFloat_FromDouble(-42.5) })) << std::endl;

◆ callable() [2/2]

ObjectPointer shlublu::Python::callable	(	std::string const &	moduleName,
		std::string const &	callableName,
		bool	forceReload = `false`
	)

Retrieves a callable object (function) by its name from a module name.

Callable objects are less likely to change than non-callable objects during the execution of the program. For this reason, pointers to callable are memorized. Multiple calls to this function with the same scope argument and callable name make the pointer retrieved in the first place to be returned, unless forceReload is set to true.

The returned pointer is under control of Python for garbage collection at shutdown() time only.

Parameters

moduleName	name of the module the callable object to retrieve belongs to
callableName	the name of the callable object to retrieve
forceReload	if true, refresh the callable object pointer before returning it and dispose of any previous version

Returns: a pointer to the retrieved callable object

Exceptions

BindingLogicError if Python is not initialized, if the module has not been imported by import(), if the object cannot be found or if it is not callable

Example

Python::import("math");
const auto fabs(Python::callable("math", "fabs"));
 
std::cout << PyFloat_AsDouble(Python::call(fabs, { PyFloat_FromDouble(-42.5) })) << std::endl;

◆ call()

ObjectHandler const& shlublu::Python::call	(	ObjectPointer	callableObject,
		ObjectHandlersList const &	args = `{}`,
		bool	keepArguments = `false`
	)

Calls a callable with the given arguments.

Once the callable returns, the references counts of the elements of args are decreased unless keepArguments is true in which case none are decreased. Should you wich to only keep some of the passed arguments, keepArguments should be set to false and controlArgument()/keepArgument() should be used with the arguments to preserve.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

callableObject	pointer to the callable object to call, typically returned by `callable()`
args	arguments of the call. They can either be obtained from previous Python calls or from CPython calls. Empty if no aregument is required.
keepArguments	if true, the references counts of the elements of `args` will not be decreased so they can be reused later on

Returns: a handler of the result of the call, which is None if the callable returns no value.

Exceptions

BindingLogicError	if Python is not initialized
BindingRuntimeError	if any issue occurs during the call

Example

const auto print(Python::callable(Python::moduleBuiltins, "print"));
 
Python::call(print, { Python::fromAscii("text to print") });

◆ tuple()

ObjectHandler shlublu::Python::tuple	(	ObjectHandlersList const &	args = `{}`,
		bool	keepArguments = `false`
	)

Creates a tuple object initialized with the given arguments.

This function steals a reference from each element of args unless keepArguments is true in which case they are all preserved. Should you wich to only preserve some of the passed arguments, keepArguments should be set to false and controlArgument()/keepArgument() should be used with the arguments to preserve.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

args	initializer of the tuple. These arguments can either be obtained from previous Python calls or from CPython calls. Empty to create an empty tuple.
keepArguments	if true, no references will be stolen from `args`

Returns: a handler of the created tuple object

Exceptions

BindingLogicError	if Python is not initialized
BindingRuntimeError	if any issue occurs during the creation of the tuple

Example

const auto tuple(Python::tuple({ PyLong_FromLong(42), Python::fromAscii("42") }));
 
// Prints the length of the tuple ("2")
Python::call
(
    Python::callable(Python::moduleBuiltins, "print"),
    {
        Python::call(Python::callable(Python::moduleBuiltins, "len"), { tuple })
    }
);

◆ list()

ObjectHandler shlublu::Python::list	(	ObjectHandlersList const &	args = `{}`,
		bool	keepArguments = `false`
	)

Creates a list object initialized with the given arguments.

This function steals a reference from each element of args unless keepArguments is true in which case they are all preserved. Should you wich to only preserve some of the passed arguments, keepArguments should be set to false and controlArgument()/keepArgument() should be used with the arguments to preserve.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

args	initializer of the list. These arguments can either be obtained from previous Python calls or from CPython calls. Empty to create an empty list.
keepArguments	if true, no references will be stolen from `args`

Returns: a handler of the created list object

Exceptions

BindingLogicError	if Python is not initialized
BindingRuntimeError	if any issue occurs during the creation of the list

Example

const auto list(Python::list({ PyLong_FromLong(42), Python::fromAscii("42") }));
 
// Prints the length of the list ("2")
Python::call
(
    Python::callable(Python::moduleBuiltins, "print"),
    {
        Python::call(Python::callable(Python::moduleBuiltins, "len"), { list })
    }
);

◆ addList()

void shlublu::Python::addList	(	ObjectHandler	list,
		ObjectHandler	item,
		bool	keepArg = `false`
	)

Adds an item to the end of a list.

This function steals a reference from item unless keepArg is true.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

list	handler of the list object to add an item to. It can either be obtained from a previous Python call or implied by a `PyObject *` pointer obtained from a CPython call.
item	handler of the item to add. It can either be obtained from a previous Python call or implied by a `PyObject *` pointer obtained from a CPython call.
keepArg	if true, no reference will be stolen from `item`

Exceptions

BindingLogicError if Python is not initialized or if list is not a list

Example

const auto list(Python::list({ PyLong_FromLong(42), Python::fromAscii("42") }));
 
Python::addList(list, PyFloat_FromDouble(42.0));
 
// Prints the length of the list ("3")
Python::call
(
    Python::callable(Python::moduleBuiltins, "print"),
    {
        Python::call(Python::callable(Python::moduleBuiltins, "len"), { list })
    }
);

◆ fromAscii()

ObjectHandler shlublu::Python::fromAscii ( std::string const & str )

Converts a string to a UTF-8 CPython string object.

The returned handler is under control of Python for garbage collection. Such a garbage collection is triggered by several functions. This is mentioned in their documentation.

Parameters

str	the string to convert

Returns: a handler of the UTF-8 string object representation of str

Exceptions

BindingLogicError if Python is not initialized

Example

Python::call
(
    Python::callable(Python::moduleBuiltins, "print"),
    { Python::fromAscii("Text to print") }
);

◆ toAscii()

std::string shlublu::Python::toAscii	(	ObjectHandler	utfStr,
		bool	keepArg = `false`
	)

Converts a UTF-8 CPython string object to a std::string.

This function steals a reference from utfStr unless keepArg is true.

Parameters

utfStr	the UTF-8 string object to convert
keepArg	if true, no reference will be stolen from `utfStr`

Returns: the std::string representation of utfStr

Exceptions

BindingLogicError if Python is not initialized or if utfStr is not a UTF-8 CPython string object

Example

Python::execute("text = 'Text to display'");
 
const auto text(Python::toAscii(Python::object(Python::moduleMain, "text")));
 
std::cout << text << std::endl;

◆ keepArgument()

ObjectHandler const& shlublu::Python::keepArgument ( ObjectHandler const & object )

Prevents an object reference from being stolen.

This function increases the reference count of an object under control of Python. This prevents reference-stealing functions from disposing of a reference that is owned by the caller.

Parameters

object a handler of the object to preserve. It shoud be under control of Python.

Returns: a new handler of object

Exceptions

BindingLogicError if Python is not initialized or if object is not under control of Python

Example

Python::execute(Python::Program({ "def giveMeFive():", "\treturn 5" }));
 
const auto math(Python::import("math"));
const auto pow(Python::callable(math, "pow"));
 
const auto objectToPreserve(Python::call(Python::callable(Python::moduleMain, "giveMeFive")));
 
// displays 1  5  25
for (int y = 0; y < 3; ++y)
{
    // Not calling 'keepArgument(objectToPreserve)' but passing straight 'objectToPreserve' would cause a crash as it would be garbage-collected after first call
    const auto res(Python::call(pow, { Python::keepArgument(objectToPreserve), PyLong_FromLong(y) }));
 
    std::cout << PyFloat_AsDouble(res) << " ";
}
 
// We still own a reference on 'objectToPreserve' here. We can reuse it, get rid of it right now using Python::forgetArgument() or let Python::shutdown() dispose of it

◆ controlArgument()

ObjectHandler const& shlublu::Python::controlArgument ( ObjectHandler object )

Places an CPython object under control of Python.

This makes Python aware of this object to include it to its references count handling process.

Parameters

object a handler of the object to be controlled. Typical use it to have it implicitely created from a PyObject * pointer obtained from the CPython API

Returns: a new handler of object

Exceptions

BindingLogicError if Python is not initialized or if object is already under control

Example

const auto math(Python::import("math"));
const auto pow(Python::callable(math, "pow"));
 
const auto objectX(Python::controlArgument(PyLong_FromLong(5))); // Python takes control of this object obtained from CPython
 
// displays 1  5  25
for (int y = 0; y < 3; ++y)
{
    // Not calling 'keepArgument(objectX)' but passing straight 'objectX' would cause a crash as it would be garbage-collected after
    // first call, while only controlled objects can be passed through Python::keepArgument()
    const auto res(Python::call(pow, { Python::keepArgument(objectX), PyLong_FromLong(y) }));
 
    std::cout << PyFloat_AsDouble(res) << " ";
}
 
// We still own a reference on 'objectX'. We can reuse it, get rid of it right now using Python::forgetArgument() or let Python::shutdown() dispose of it

◆ forgetArgument()

void shlublu::Python::forgetArgument ( ObjectHandler const & object )

Get rid of a reference of an object under control.

This function allows saving memory by decreasing the reference count of an object that is no longer used without waiting for shutdown() to do it.

Parameters

object a handler of the object to forget

Exceptions

BindingLogicError if Python is not initialized, if object is not under control, or if the references count of object is zero or less

Example

const auto randint(Python::callable(Python::import("random"), "randint"));
const auto min(Python::controlArgument(PyLong_FromLong(0)));
const auto max(Python::controlArgument(PyLong_FromLong(10)));
 
// Prints 100000 random numbers between min and max included
for (int i = 0; i < 100000; ++i)
{
    const auto result(Python::call(randint, { Python::keepArgument(min), Python::keepArgument(max) }));
 
    std::cout << PyLong_AsLong(result) << std::endl;
 
    // We get rid of 'result' right away as we won't use it anymore.
    // Otherwise, with many iterations, a large amount of memory could end up wasted waiting for 'Python::shutdown()' to dispose of these references.
    // In a lesser extent this might also have an impact on performances as the internal references table maintain by Python would get bigger and bigger.
    Python::forgetArgument(result);
}
 
// Let's say we leave 'Python::shutdown()' to dispose of the remaining references of 'min' and 'max', that's ok.

◆ beginCriticalSection()

void shlublu::Python::beginCriticalSection ( )

Enters a critical section, preventing other threads from entering any Python critical section.

This function is relevant in multi-threaded applications, either to guarantee data consistency or to prevent concurrent calls to native or CPython functions from causing a crash (see note regarding concurrency in the detailed description of this namespace).

Calls to this function should be followed in the same thread by as many calls to endCriticalSection(). Not doing so is a cause of deadlocks.

Exceptions

BindingLogicError if Python is not initialized.

Example

Python::init("pythonBinding");
 
const long nbIt(15000L);
std::vector<Python::ObjectHandler> values;
 
std::thread producer
(
    [nbIt, &values]()
    {
        Python::execute(Python::Program({ "def dbl(x):", "\treturn 2 * x" }));
        const auto dbl(Python::callable(Python::moduleMain, "dbl"));
 
        for (long i = 0; i < nbIt; ++i)
        {
            Python::beginCriticalSection();
 
            const auto res(Python::call(dbl, { PyLong_FromLong(i) }));
            values.push_back(res);
 
            Python::endCriticalSection();
        }
    }
);
 
std::thread consumer
{
    [nbIt, &values]()
    {
        long expected(0);
 
        while (expected < (2 * nbIt))
        {
            Python::beginCriticalSection();
 
            if (values.size())
            {
                const auto obj(*values.begin());
 
                // do something with 'obj'
 
                Python::forgetArgument(obj);
                values.erase(values.begin());
 
                Python::endCriticalSection();
 
                expected += 2;
            }
            else
            {
                Python::endCriticalSection();
 
                std::this_thread::sleep_for(std::chrono::milliseconds(5));
            }
        }
    }
};
 
producer.join();
consumer.join();
 
Python::shutdown();

◆ endCriticalSection()

void shlublu::Python::endCriticalSection ( )

Exits a critical section, allowing other threads to enter a Python critical section.

Calls to this function should match calls to beginCriticalSection() performed in the same thread.

Exceptions

BindingLogicError if this call doesn't match a previous call to beginCriticalSection() performed in the same thread.

◆ operator==()

bool shlublu::Python::operator==	(	ObjectHandler const &	lhs,
		ObjectHandler const &	rhs
	)

Equality operator.

Compare use cases represented by two instances ObjectHandler. Refers to the ID to do so as two identical ID should come with two identical object pointers while the reverse is not true.

Parameters

lhs	left operand
rhs	right operand

◆ operator!=()

bool shlublu::Python::operator!=	(	ObjectHandler const &	lhs,
		ObjectHandler const &	rhs
	)

Inequality operator.

Compare use cases represented by two instances ObjectHandler. Refers to the ID to do so as two identical ID should come with two identical object pointers while the reverse is not true.

Parameters

lhs	left operand
rhs	right operand

Variable Documentation

◆ moduleMain

const std::string shlublu::Python::moduleMain

Main module ("__main__").

Imported automatically at init() time.

◆ moduleBuiltins

const std::string shlublu::Python::moduleBuiltins

Built-ins module ("builtins").

Imported automatically at init() time.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ ObjectPointer

◆ Program

Function Documentation

◆ isInitialized()

◆ init()

◆ shutdown()

◆ execute() [1/2]

◆ execute() [2/2]

◆ import()

◆ module()

◆ object() [1/2]

◆ object() [2/2]

◆ callable() [1/2]

◆ callable() [2/2]

◆ call()

◆ tuple()

◆ list()

◆ addList()

◆ fromAscii()

◆ toAscii()

◆ keepArgument()

◆ controlArgument()

◆ forgetArgument()

◆ beginCriticalSection()

◆ endCriticalSection()

◆ operator==()

◆ operator!=()

Variable Documentation

◆ moduleMain

◆ moduleBuiltins