Changeset 415ddd for src/documentation/userinterfaces

Timestamp:

May 20, 2014, 9:14:56 AM (11 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

74459a

Parents:

975b83

git-author:

Frederik Heber <heber@…> (08/26/13 22:56:36)

git-committer:

Frederik Heber <heber@…> (05/20/14 09:14:56)

Message:

ActionQueue now contains a run thread.

• otherwise the progress bar of the QtMainWindow cannot be seen as waitForResults() takes up all of the executing thread.
• added mutex for operations modifying the queue.
• added ActionQueue::run() and ::stop(), used by friend stopQueue().
• insertAction() now makes use of a tempqueue that is added to true queue during run() instead of calling the actions directly.
• new stopQueue() in cleanUp.hpp is used by module_exit in pyMoleCuilder and in main() before saveAll().
• cleanup: printTiming() requires now list of action tokens and added new stopAndPurgeQueue() to place waiting for Actions to end into extra function.
• added ActionQueue::wait() which allows for synchronization in python scripts, is ignored in session python scripts. Otherwise we wait for ActionQueue's queue to empty during execution of load-session which hangs.
• DOCU: added note to python documentation.
• added waitQueue() also to purgeStaticInstances().
• static UIFactory::isFactoryPresent() added that allows checking whether we have a UI or are executed within a python script (i.e. pyMoleCuilder).
• DOCU: Extended docu on threads and who this affects python scripts.
• TESTFIX: changed regression tests on storing python sessions.

File:

• src/documentation/userinterfaces/python.dox (modified) (6 diffs)

src/documentation/userinterfaces/python.dox

@@ -20 +20 @@
  *  script.
  *
- *  This is done in \b src/Actions/pyMoleCuilder.cpp.
+ *  This is done in \b src/Python/PythonScripting.cpp.
  *
  *  There again some preprocessor magic is happening. One the one hand we
@@ -43 +43 @@
  *  mol.SelectAtomById("0")
  *  mol.AtomRemove()
+ *  mol.wait()
+ *  mol.getSelectedMolarMass()
+ *  mol.wait()
  *  \endcode
  *  which loads a file \b test.xyz into the (internal) World, selects the first
- *  atom and removes it.
+ *  atom and removes it. Notice \b mol.wait() at the end. This might be necessary
+ *  as actions are executed in a different thread than the python script itself.
+ *  Hence, if you require values from molecuilder you have to make sure that
+ *  all your actions have been processed by this second thread. That's what
+ *  wait() is good for. It waits until action queue thread is idle. Then you
+ *  can be sure that molecuilder has removed all atoms, performed all selections
+ *  and any value you retrieve is up-to-date.
+ *
+ *  Note that there are two \b wait()s present in the example. As the Actions
+ *  are executed in another thread and the above commands just tell the MoleCuilder
+ *  library (the ActionQueue to be precise) to enqueue the requested action,
+ *  we have to wait (in the main thread) until the actions actually have been
+ *  executed before we continue (i.e. when we need the new state where the
+ *  atoms have been removed) and before we \b terminate!
  *
  *  \section userinterfaces-python-running Running a test script
@@ -72 +88 @@
  *  \code
  *  pyMoleCuilder.WorldInput("test.xyz")
+ *  pyMoleCuilder.wait()
  *  \endcode
  *
@@ -78 +95 @@
  *  \code
  *  pyMoleCuilder.SelectionAllMolecules()
+ *  pyMoleCuilder.wait()
  *  \endcode
  *
@@ -84 +102 @@
  *  \code
  *  pyMoleCuilder.SelectAtomById("0")
+ *  pyMoleCuilder.wait()
  *  \endcode
+ *
+ *  \warning Again, take note of the added wait()s that ensure the all enqueued
+ *  actions also have been executed. This is especially important in scripts as
+ *  otherwise your script may deadlock. That's because ActionQueue's destructor
+ *  waits for the thread that executes the actions to end, and in another thread
+ *  we still want to access to ActionQueue whose instance is however locked as
+ *  it is about the get destroyed.
  *
  *  \subsection userinterfaces-python-notes-cleanup Cleaning up or reset state ...
@@ -115 +141 @@
  *  gives you the docu string on WorldInputAction.
  *
+ * \subsection userinterfaces-python-notes-wait Waiting for the action queue
  *
- * \date 2013-03-18
+ * Note again that actions are executed in a different thread as the python
+ * script. Hence, we require synchronization at certain intervals where you
+ * require molecuilder to be up to speed. All commands you executed such
+ * as
+ * \code
+ * import pyMoleCuilder as mol
+ * mol.WorldInput("foo.xyz")
+ * mol.wait()
+ * \endcode
+ * just queue this specific input action but not execute it right away. That's
+ * left to the other thread. Hence, you need to wait() before:
+ * -# you access mol.get...() functions as these are not actions themselves.
+ * -# you need to have files written by molecuilder to be parsed in the python
+ *    script.
+ *
+ *
+ * \date 2013-09-28
  *
  */