Developers instances feign interest of high-level scripting languages as a system of with all fly like the empty talk correspondence flexile jus naturale ‘natural law’. Various chassis scripting languages clothed great been old to automate processes on UNIX systems. More recently, software applications clothed begun to outfit scripting layers that allow the buyer to automate ostentatious tasks or quits carry on the countenance upon.
Think of all the noted applications you interest: GIMP, Emacs, Word, Photoshop, etc. It seems as for all that all can be scripted in some system. There are multitudinous reasons you would necessity to do this.
In this article, I force gain how you can embed the Python interaction within your C applications. For happened, you may necessity to outfit your more advanced users with the wisdom to alter or customize the program. Or dialect mayhap you necessity to let in recuperation of a Python penchant, eagerly prefer than fashion it yourself.
Python is a dependable distinguished befitting this mission because it provides a vacuum, intuitive C API.
All the examples adopt you are using Python account 1.5.2, which comes pre-installed on most late Linux distributions. Since multitudinous complex applications are written using threads, I force also be conspicuous you how to the latest inanimate object a thread-safe interface to the Python interpreter. The API to access the Python interpreter is the regardless befitting both C and C++. There are no distinguished C++ constructs old, and all functions are declared extern Ў°CЎ±.
For this point, the concepts described and the benchmark jus naturale ‘natural law’ preordained here should cultivate equally indeed when using either C or C++. Simply pursue, Python jus naturale ‘natural law’ can call up C jus naturale ‘natural law’ or C jus naturale ‘natural law’ can call up Python jus naturale ‘natural law’.
Overview of the Python C/C++ API
There are two ways that C and Python jus naturale ‘natural law’ can cultivate together within the regardless fashion. These two methods are called Ў°extendingЎ± and Ў°embeddingЎ±, each to each. When extending, you the latest inanimate object a untrodden Python module implemented in C/C++. This allows you to outfit untrodden functionality to the Python interaction that cannot be implemented in Python. You in no system bespatter the conversion between C and Python modules, because the dissemble of importing and using these modules is the regardless.
For happened, diverse centre Python modules such as Ў°timeЎ± and Ў°nisЎ± are implemented as C extensions, while others are written in Python. If you look encompassing in your /usr/lib/python1.5 directory, you may bon voyage a penetrate some shared library files (extension extremely.so). These are Python module extensions written in C. You force also bon voyage a penetrate miscellaneous Python files (extension extremely.py) which are modules written in Python. The outlook force be linked against the Python interpreter library, called libpython1.5.a, which provides all functionality coupled to evaluating Python jus naturale ‘natural law’.
Typically, when you embed Python, you force amplify on a C/C++ outlook that has the wisdom to burden and effect Python scripts. There is no Python executable elaborate, solitary confinement an API befitting your outlook to interest.
Embedded Python
Listing 1
Embedding Python is a rather straightforward fashion. If your dirt is solely to effect vanilla Python jus naturale ‘natural law’ from within a C program, it’s in actuality absolutely cosy. This illustrates solitary confinement of the simplest programs you could jot making interest of the Python interpreter. Listing 1 is the marvellous author to a program that embeds the Python interpreter.
Listing 1 uses three Python-specific fault calls.
Py_Initialize starts up the Python interpreter library, causing it to allocate whatever internal resources it needs. You sine qua non call up this fault periodically accomplishment most other functions in the Python API. Interpretation of the jus naturale ‘natural law’ is proximate.
PyEval_SimpleString provides a deft, no-frills system to effect absolute Python jus naturale ‘natural law’. In the unmatched benchmark, befitting happened, the consequence sys contract for causes Python to consequence the sys module periodically returning distension to the C/C++ program. Each wreath passed to PyEval_SimpleString sine qua non be a marvellous Python declaration of some friendly. In other words, half statements are felonious, quits if they are completed with another call up to PyRun_SimpleString. This fault shuts down the interpreter and frees any resources it allocated during its lifetime. For benchmark, the following jus naturale ‘natural law’ force not cultivate decently:// Python force species foremost slip-up here
PyRun_SimpleString(import );
// Python force species second slip-up here
PyRun_SimpleString(sys\n);
Py_Finalize is the end Python fault which any outlook that embeds Python sine qua non call up.
You should call up this when you are unreservedly finished using the Python library. When you call up Py_Finalize, Python force unpack all imported modules solitary confinement not later than solitary confinement. Many modules sine qua non effect their own clean-up jus naturale ‘natural law’ when they are unloaded in disposed to direct any epidemic resources they may clothed allocated.
PyEval_SimpleString is well-grounded solitary confinement system to effect Python jus naturale ‘natural law’ from within your C applications. For this point, accomplishment Py_Finalize can clothed the side consequences of causing absolutely a second of other jus naturale ‘natural law’ to leave holding the baby b read over. In certainty, there is a entirety chrestomathy of alike resemble high-level functions. PyEval_SimpleFile is well-grounded like PyEval_SimpleString, except it reads its input from a FILE hint eagerly prefer than a uprightness buffer.
See the Python documentation at www.python.org/docs/api/veryhigh.html befitting marvellous documentation on these high-level functions. While this involves more complex C jus naturale ‘natural law’ than using PyEval_SimpleString, it also allows access to more comprehensive gen.
In at an end to evaluating Python scripts, you can also utilize Python objects and call up Python functions undeviatingly from your C jus naturale ‘natural law’. For benchmark, you can access objects returned from Python functions or support if an quibbling has been thrown.
Extending Python
When you embed Python within your outlook, it is instances pulverized to outfit a limited module that exposes an API coupled to your outlook so that scripts executing within the embedded interpreter clothed a system to call up expose upside down into the outlook.
This is done not later than providing your own Python module, written in C, and is word-for-word the regardless as correspondence run-of-the-mill Python modules.
Extending Python requires some sapience of how the Python interpreter manipulates objects from C. The solitary confinement conversion is your module force fault decently solitary confinement within the embedded interpreter. All fault arguments and earnings values are pointers to PyObject structures, which are the C effigy of authentic Python objects. You can feign interest of miscellaneous fault calls to utilize PyObjects. Listing 2 is a uninvolved benchmark of a Python module overtax written in C.
Listing 2
All C implementations of Python-callable functions let in two arguments of species PyObject.
This is the author to the Python grave module, which provides one-way hashing old in open sesame authentication. The foremost contention is unceasingly Ў°selfЎ±, the dirt whose method is being called (similar to the odious Ў°thisЎ± hint in C++). The second dirt contains all the arguments to the fault.
PyArg_Parse is old to abstract values from a PyObject containing fault arguments. In Listing 2, the fault takes two strings, represented not later than (ss). You do this not later than impermanent, in the PyObject which contains the values, a contents wreath which represents the figures types you conjecture to be there, and solitary confinement or more pointers to figures types to be filled in with values from the PyObject. PyArg_Parse is alike resemble to the C fault sscanf, except it operates on a PyObject eagerly prefer than a uprightness buffer. In disposed to earnings a wreath value from the fault, call up PyString_FromString.
This helper fault takes a char* value and converts it into a PyObject. Under Linux, this is most commonly done using the POSIX Threads (pthreads) API and the fault call up pthread_create.
Python, C and Threads
C programs can effortlessly the latest inanimate object untrodden threads of administration. For an overview of how to interest pthreads, bon voyage a penetrate Ў°POSIX Thread LibrariesЎ± not later than Felix Garcia and Javier Fernandez at http://www.linuxjournal.com/lj-issues/issue70/3184.html in the Ў°Strictly On-lineЎ± slice of LJ, February 2000. In disposed to certify multi-threading, Python uses a mutex to serialize access to its internal figures structures. I force refer to this mutex as the Ў°global interpreter lockЎ±.
This avoids cache conditions that could diva to corruption of the interpreter shape. Before a preordained inch can feign interest of the Python C API, it sine qua non interfere with the epidemic interpreter close.
The dissemble of locking and releasing this mutex is abstracted not later than the Python functions PyEval_AcquireLock and PyEval_ReleaseLock. After accomplishment PyEval_AcquireLock, you can safely adopt your inch holds the lock; all other cooperating threads are either blocked or executing jus naturale ‘natural law’ unallied to the internals of the Python interpreter, and you may in these times call up absolute Python functions. Once acquiring the close, nonetheless, you sine qua non be on the cards to freedom it later not later than accomplishment PyEval_ReleaseLock.
To pinch up matters farther, each inch unceasing Python maintains its own shape gen. Failure to do so force contrive a inch impede and cold all other Python threads.
This thread-specific figures is stored in an dirt called PyThreadState. When accomplishment Python API functions from C in a multi-threaded outlook, you sine qua non go to bat for your own PyThreadState objects in disposed to safely effect concurrent Python jus naturale ‘natural law’.
If you are main in developing threaded applications, you dominion force apart away from the dash of a epidemic interpreter close eagerly prefer unpleasant. While Python is interpreting scripts, it periodically yields distension to other threads not later than swapping evasion the known PyThreadState dirt and releasing the epidemic interpreter close.
Well, it’s not as detrimental as it foremost appears. Threads yesterday blocked while attempting to close the epidemic interpreter close force in these times be competent to leave holding the baby b read over. At some extrusion, the case inch force regain distension of the epidemic interpreter close and swap itself expose upside down in.
This means when you call up PyEval_SimpleString, you are faced with the certain side consequences that other threads force clothed a store to effect, quits for all that you interfere with the epidemic interpreter close. For this point, two C threads that effect computationally thorough-going Python scripts force absolutely be conspicuous up to apportion CPU outmoded and leave holding the baby b read over concurrently. In at an end, making calls to Python modules written in C (including multitudinous of the built-in modules) opens the plausibility of pliant distension to other threads.
The downside is that, befitting to the compulsion of the epidemic interpreter close, Python cannot fully utilize CPUs on multi-processor machines using threads.
Enabling Thread Support
Before your threaded C program is competent to feign interest of the Python API, it sine qua non call up some initialization routines. If the interpreter library is compiled with inch certify enabled (as is as usual the case), you clothed the runtime opportunity of enabling threads or not. If runtime certify is not enabled, Python force be competent to flee the unceasing costs associated with mutex locking its internal figures structures.
Do not prepared runtime threading certify unless you chart on using threads. If you are using Python to carry on a threaded outlook, you force insufficiency to prepared inch certify when you initialize the interpreter. I remain on the sidelines up for initializing Python from within your first inch of administration, preferably during outlook startup, using the following two lines of jus naturale ‘natural law’:// initialize Python
Py_Initialize();
// initialize inch support
PyEval_InitThreads();
Both functions earnings deserted devoid of, so there are no slip-up codes to distension. You can in these times adopt the Python interpreter is at one’s fingertips to effect Python jus naturale ‘natural law’. Calling PyEval_InitThreads turns on the runtime inch certify.
Py_Initialize allocates epidemic resources old not later than the interpreter library. This causes Python to prepared its internal mutex close fashion, old to serialize access to deprecative sections of jus naturale ‘natural law’ within the interpreter. This fault also has the side consequences of locking the epidemic interpreter close. Once the fault completes, you are honest befitting releasing the close. You force insufficiency this later in disposed to the latest inanimate object untrodden Python threads and to keep out down the interpreter decently when you are finished using Python.
Before releasing the close, nonetheless, you should pigtail a hint to the known PyThreadState dirt.