Comments + style

Utilities/Python/vtkPython.h

@@ -102,48 +102,25 @@ they are system headers.  Do NOT add any #undef lines here.  */
 #undef toupper
 #endif
 
-// Use vtkPythonScopeGilEnsurer to protect some parts of python code.
-// Some classes are already protected with it (mainly used in paraview):
-// vtkPythonInteractiveInterpreter
-// vtkPythonInterpreter
-// vtkPythonCommand
-// vtkSmartPyObject
-// 
-// others aren't:
-// PyVTKObject
-// PyVTKSpecialObject
-// PyVTKMethodDescriptor
-// vtkPythonOverload
-// vtkPythonUtil
-// PyVTKMutableObject
-// PyVTKNamespace
-// PyVTKTemplate
-// vtkPythonView ( paraview )
-// pqPythonDebugLeaksView (paraview)
-// 
-// others are not protected, but can be considered not 
-// in need of protection for different reasons
-// eg, used only in wrapping, not used, standalone executable, 3rd party :
-// vtkPythonAppInit
-// vtkPythonArgs
-// PyVTKExtras
-// vtkMatplotlibMathTextUtilities
-// vtkPythonAlgorithm
-// vtkWebUtilities
-// vtkMPI4PyCommunicator
-// vtkClientServerInterpreterPython ( paraview )
-// pqPythonEventSource (QtTesting)
-// pqPythonEventSourceImage (QtTesting)
-// Plugin code ( xdmf2, pvblot)
-
+// Description:
+// RAII class to manage Python threading using GIL (Global Interpreter Lock).
+// GIL is locked at object creation and unlocked at destruction.
+// Note: behaviour of this class depends on VTK_PYTHON_FULL_THREADSAFE.
 class vtkPythonScopeGilEnsurer 
 {
 public:
+  // Description:
+  // If force is TRUE, lock/unlock even if VTK_PYTHON_FULL_THREADSAFE is not defined.
+  // If force is FALSE, lock/unlock is only performed if VTK_PYTHON_FULL_THREADSAFE is
+  // defined.
+  // If noRelease is TRUE, unlock will not be called at object destruction. This is used
+  // for specific python function calls like PyFinalize which already take 
+  // care of releasing the GIL.
   vtkPythonScopeGilEnsurer(bool force = false, bool noRelease = false)
     : State(PyGILState_UNLOCKED)
-    {
+  {
 #ifdef VTK_PYTHON_FULL_THREADSAFE
-    // Force is always true with FULL_THREADSAFE
+    // Force is always true with VTK_PYTHON_FULL_THREADSAFE
     force = true;
 #endif
     this->Force = force;
@@ -152,14 +129,15 @@ public:
       {
       this->State = PyGILState_Ensure();
       }
-    }
+  }
+ 
   ~vtkPythonScopeGilEnsurer()
-    {
+  {
     if (this->Force && !this->NoRelease)
       {
       PyGILState_Release(this->State);
       }
-    }
+  }
 
 private:
   PyGILState_STATE State;

Utilities/PythonInterpreter/vtkPythonInterpreter.cxx

@@ -69,7 +69,7 @@ namespace
 
   inline void vtkPrependPythonPath(const char* pathtoadd)
     {
-    vtkPythonScopeGilEnsurer gilEnsurer(true);  
+    vtkPythonScopeGilEnsurer gilEnsurer(true);
     PyObject* path = PySys_GetObject(const_cast<char*>("path"));
 #if PY_VERSION_HEX >= 0x03000000
     PyObject* newpath = PyUnicode_FromString(pathtoadd);
@@ -87,7 +87,6 @@ bool vtkPythonInterpreter::ConsoleBuffering = false;
 std::string vtkPythonInterpreter::StdErrBuffer;
 std::string vtkPythonInterpreter::StdOutBuffer;
 
-
 vtkStandardNewMacro(vtkPythonInterpreter);
 //----------------------------------------------------------------------------
 vtkPythonInterpreter::vtkPythonInterpreter()
@@ -152,7 +151,7 @@ bool vtkPythonInterpreter::Initialize(int initsigs /*=0*/)
       {
       PyEval_SaveThread(); // release GIL
       }
-#endif    
+#endif
 
     // HACK: Calling PyRun_SimpleString for the first time for some reason results in
     // a "\n" message being generated which is causing the error dialog to
@@ -168,7 +167,7 @@ bool vtkPythonInterpreter::Initialize(int initsigs /*=0*/)
 
     // Redirect Python's stdout and stderr and stdin - GIL protected operation
     {
-    vtkPythonScopeGilEnsurer gilEnsurer;  
+    vtkPythonScopeGilEnsurer gilEnsurer;
     PySys_SetObject(const_cast<char*>("stdout"),
       reinterpret_cast<PyObject*>(wrapperOut));
     PySys_SetObject(const_cast<char*>("stderr"),
@@ -197,7 +196,8 @@ void vtkPythonInterpreter::Finalize()
   if (Py_IsInitialized() != 0)
     {
     NotifyInterpreters(vtkCommand::ExitEvent);
-    vtkPythonScopeGilEnsurer gilEnsurer(false, true);  
+    vtkPythonScopeGilEnsurer gilEnsurer(false, true); 
+    // Py_Finalize will take care of relasing gil
     Py_Finalize();
     }
 }
@@ -320,7 +320,7 @@ int vtkPythonInterpreter::PyMain(int argc, char** argv)
       return 1;
       }
     }
-  vtkPythonScopeGilEnsurer gilEnsurer;  
+  vtkPythonScopeGilEnsurer gilEnsurer;
   int res = Py_Main(argc, argvWide);
   PyMem_Free(argv0);
   for (int i = 0; i < argc; i++)
@@ -331,8 +331,8 @@ int vtkPythonInterpreter::PyMain(int argc, char** argv)
   delete [] argvWide2;
   return res;
 #else
-    
-  vtkPythonScopeGilEnsurer gilEnsurer( false, true);  
+
+  vtkPythonScopeGilEnsurer gilEnsurer(false, true);
   return Py_Main(argc, argv);
 #endif
 }
@@ -351,7 +351,7 @@ int vtkPythonInterpreter::RunSimpleString(const char* script)
   // The cast is necessary because PyRun_SimpleString() hasn't always been const-correct
   int pyReturn;
     {
-    vtkPythonScopeGilEnsurer gilEnsurer;  
+    vtkPythonScopeGilEnsurer gilEnsurer;
     pyReturn = PyRun_SimpleString(const_cast<char*>(buffer.c_str()));
     }