jep

Class MainInterpreter

java.lang.Object

jep.MainInterpreter

All Implemented Interfaces:

java.lang.AutoCloseable

public final class MainInterpreter
extends java.lang.Object
implements java.lang.AutoCloseable

The main Python interpreter that all sub-interpreters will be created from. In a simpler embedded Python project, a single Python interpreter would be used and all would be good. However, since Jep supports multithreading with multiple sub-interpreters, we need the MainInterpreter to work around some issues. The MainInterpreter is used to avoid potential deadlocks. Python can deadlock when trying to acquire the GIL through methods such as PyGILState_*. While Jep does not use those methods, CPython extensions such as numpy do. The deadlock can occur if there is more than one PyThreadState per thread. To get around this, the MainInterpreter creates a unique thread that initializes Python and keeps this thread around forever. This ensures that any new sub-interpreters cannot be created on the same thread as the main Python interpreter. The MainInterpreter is also used to support shared modules. While each sub-interpreter is fairly sandboxed, in practice this does not always work well with CPython extensions. In particular, disposing of a sub-interpreter that has imported a CPython extension may cause some of the CPython extension's objects to be garbage collected. To get around this, shared modules import on the main interpreter's thread so they can be shared amongst sub-interpreters and will never be garbage collected. For more information about why the MainInterpreter class exists, see Sub-interpreter bugs and caveats.

Since:

3.8

Method Summary

Modifier and Type	Method and Description
void	close() Stop the interpreter thread.
static void	setInitParams(PyConfig config) Sets interpreter settings for the main Python interpreter.
static void	setJepLibraryPath(java.lang.String path) Sets the path of the jep native library.
static void	setSharedModulesArgv(java.lang.String... argv) Sets the sys.argv values on the main interpreter.
void	sharedImport(java.lang.String module) Import a module into the main interpreter on the correct thread for that interpreter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

sharedImport

public void sharedImport(java.lang.String module)
                  throws JepException

Import a module into the main interpreter on the correct thread for that interpreter. This is called from the Python shared modules import hook to create a module needed by a SubInterpreter.

Parameters:

module - the name of the module to import

Throws:

JepException - if an error occurs

close

public void close()

Stop the interpreter thread.

Specified by:

close in interface java.lang.AutoCloseable

setInitParams

public static void setInitParams(PyConfig config)
                          throws java.lang.IllegalStateException

Sets interpreter settings for the main Python interpreter. This method must be called before the first Interpreter instance is created in the process.

Parameters:

config - the python configuration to use.

Throws:

java.lang.IllegalStateException - if called after the Python interpreter is initialized

Since:

3.6

setSharedModulesArgv

public static void setSharedModulesArgv(java.lang.String... argv)
                                 throws java.lang.IllegalStateException

Sets the sys.argv values on the main interpreter. This method must be called before the first Interpreter instance is created in the process.

Parameters:

argv - the arguments to be set on Python's sys.argv for the main interpreter

Throws:

java.lang.IllegalStateException - if called after the Python interpreter is initialized

Since:

3.7

setJepLibraryPath

public static void setJepLibraryPath(java.lang.String path)
                              throws java.lang.IllegalStateException

Sets the path of the jep native library. The location should be a path that can be passed to System.load(String). This method must be called before the first Interpreter instance is created in the process.

Parameters:

path - the path of the jep native library, an absolute path leading to a file that is often named libjep.so or libjep.dll.

Throws:

java.lang.IllegalStateException - if called after the Python interpreter is initialized

Since:

3.9