Class to manage the preparation of Python for the Interactive Robot Environment, and for launching the IRE IDE and shell. More...

#include <ireFramework.h>

Static Public Member Functions
static ireFramework *	Instance (void)

static void	InitShell (void) throw (std::runtime_error)

static void	FinalizeShell (void) throw (std::runtime_error)

static void	LaunchIREShell (const char *startup="", bool newPythonThread=false, bool useIPython=false, bool useStreambuf=true) throw (std::runtime_error)

static void *	RunIRE_wxPython (const char *startup)

static void *	RunIRE_IPython (const char *startup)

static void	JoinIREShell (double timeout)

static bool	IsStarting ()

static bool	IsActive ()

static bool	IsFinished ()

static void	SetActiveFlag (bool flag)

static bool	IsInitialized ()

static void	Reset ()

static void	UnblockThreads ()

static void	BlockThreads ()

static void	PrintLog (const char *str, int len)

Protected Member Functions
	ireFramework ()

	~ireFramework ()

Detailed Description

Class to manage the preparation of Python for the Interactive Robot Environment, and for launching the IRE IDE and shell.

The goal of the IRE is to be mindlessly simple to incorporate in already complicated applications.

The purpose of this class is to abstract the mechanics of preparing and launching Python in general and the IRE in particular from the end user. It is also used to ensure creation of a single extended Python shell with global scope.

This class is instantiated, and runs as a singleton object. The method is borrowed from Design Principles and the CISST Logger.

Note: The IRE is not thread-safe; all threads will run the IRE in the Python shell created by this singleton class. This behavior is DESIRED; we are attempting to prevent multiple copies of the Object Register from being created from within the same application. Note that it is theoretically possible for the user to nevertheless create a new copy of the Object Register referenced by this application from within a separate Python shell (the IRE IDE permits spawning new shells).

Constructor & Destructor Documentation

ireFramework::ireFramework ( )

inlineprotected

Constructor for this singleton object. Initialize the Python subsystem upon creation. InitShellInstance changes the IRE state from IRE_NOT_CONSTRUCTED to IRE_INITIALIZED.

ireFramework::~ireFramework ( )

inlineprotected

Dereferences everything and cleans Python shell. Changes the IRE state to IRE_FINISHED.

Member Function Documentation

static void ireFramework::BlockThreads ( )

static

Re-acquire the global interpreter lock. This is intended to be used as a callback (e.g., in osaThreadSignal)

static void ireFramework::FinalizeShell	(	void	)
throw	(	std::runtime_error
	)

inlinestatic

Called explicitly from the class destructor, it removes all references to the Python shell. Python is then free to clean itself up. If the application wishes to restart the IRE, it will be necessary to explicitly call InitShell(). Changes IRE state to IRE_FINISHED.

static void ireFramework::InitShell	(	void	)
throw	(	std::runtime_error
	)

inlinestatic

Initializes the Python environment. Called from the constructor, the user needs never call this function explicitly. As ireFramework is a singleton object, the underlying Python shell will have application scope ONLY. The "irepy" package will remain instantiated for the duration of the application. All modules loaded and variables created from this class will remain in scope; note that this does NOT include objects created from within the IRE IDE shell. Changes IRE state to IRE_INITIALIZED.

static ireFramework* ireFramework::Instance ( void )

static

Return a pointer to the instantiated instance of this object. Note that the IRE state will change from IRE_NOT_CONSTRUCTED to IRE_INITIALIZED on the first call to this function.

static bool ireFramework::IsActive ( )

static

Check whether IRE shell is active (i.e., all initialization complete and wxPython app loop entered). Note that there will be some time delay between when LaunchIREShell() is invoked and when IsActive() becomes true.

static bool ireFramework::IsFinished ( )

static

Check whether the IRE has been exited.

static bool ireFramework::IsInitialized ( )

static

Check whether the Python interpreter has been initialized (i.e., the ireFramework instance has been created and FinalizeIREShell() has not been called).

static bool ireFramework::IsStarting ( )

static

Check whether the IRE shell is (or could be) starting (i.e., not active and not finished). We do not check the "obvious" case of the IRE state being IRE_LAUNCHED because if the IRE is being launched from a new C++ thread, the thread may not yet have been created.

static void ireFramework::JoinIREShell ( double timeout )

inlinestatic

Wait for IRE shell to finish (if started in a new Python thread). Specify a negative timeout to wait forever.

static void ireFramework::LaunchIREShell	(	const char *	startup = `""`,
		bool	newPythonThread = `false`,
		bool	useIPython = `false`,
		bool	useStreambuf = `true`
	)
throw	(	std::runtime_error
	)

inlinestatic

Loads the "irepy" Python IRE package and calls the "launch()" method to launch the GUI.

Note: Although the "irepy" package itself remains loaded for the duration of the application, any variables/objects instantiated within the IRE interpreter are contained in a separate, session-scope interpreter; they will not be available from the C++ environment after the IRE GUI is shut down.

The Python shell will first run the "startup" string. This can be used, for example, to import application-specific Python scripts. The "startup" string is not declared const because that would not be compatible with PySys_SetArgv().

If the newPythonThread parameter is true, the IRE will be started in a separate thread. Note, however, that the C++ code will have to periodically call JoinIREShell(); otherwise, the C++ program will not relinquish any execution time to the IRE thread. An alternate implementation would be to create the IRE thread in the C++ code before launching the IRE. This, however, is less portable and would best be implemented using cisstOSAbstraction.

If the useIPython parameter is true, then IPython shell will be started instead of the IRE (GUI). IPython is an enhanced interactive Python shell, allowing autocompletion, etc. For more information, see http://ipython.scipy.org/moin/

If the useStreambuf field is true, the IRE logger will show locally-generated log messages (using cmnCallbackStreambuf). When using the system-wide logger, it is recommended to set this to false.

If the IRE state on entry is IRE_INITIALIZED, this method changes it to IRE_LAUNCHED; otherwise, it throws an exception. When the Python code finishes its initialization, it will call a callback function to change the state to IRE_ACTIVE prior to entering the wxPython main event loop. On exit from the event loop, it will call the callback function to change the state to IRE_FINISHED.

static void ireFramework::PrintLog	(	const char *	str,
		int	len
	)

static

Write a string to the logger window

static void ireFramework::Reset ( )

static

If the current IRE state is IRE_FINISHED, change it to IRE_INITIALIZED (calling InitShell if necessary). This is provided to facililate relaunching of the IRE.

static void* ireFramework::RunIRE_IPython ( const char * startup )

inlinestatic

Single argument function that can be passed directly to osaThread::Create, e.g.,:

osaThread IreThread;

IreThread.Create<char *> (&ireFramework::RunIRE_IPython, "print 'using IPython'");

static void* ireFramework::RunIRE_wxPython ( const char * startup )

inlinestatic

Single argument function that can be passed directly to osaThread::Create, e.g.,:

osaThread IreThread;

IreThread.Create<char *> (&ireFramework::RunIRE_wxPython, "print 'using wxPython'");

static void ireFramework::SetActiveFlag ( bool flag )

static

This is provided as a callback to the Python code that launches the IRE, so that it can change the state to IRE_ACTIVE or IRE_FINISHED.

static void ireFramework::UnblockThreads ( )

static

Release the global interpreter lock. This is intended to be used as a callback (e.g., in osaThreadSignal)

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

/home/adeguet1/catkin_ws/src/cisst-saw/cisst/cisstInteractive/ireFramework.h

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation