Changeset 59f1bc for src/documentation/constructs/qt-gui.dox

Timestamp:

Feb 14, 2016, 12:34:29 PM (9 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:

23221f

Parents:

03e69e

git-author:

Frederik Heber <heber@…> (01/06/16 08:36:58)

git-committer:

Frederik Heber <heber@…> (02/14/16 12:34:29)

Message:

All ..Inserted/..Removed signals now go through GLWorldScene.

• this should enforce synchronicity of the signals. If we mix direct and queued connections, then this cannot be ensured.
• the idea is that GLWorldScene gets all Inserted/Removed signals for atoms and molecules from the QtObservedInstanceBoard. It connects to each QtObservedMolecule and thus can call the GLMoleculeObject_molecule's atomInserted, atomRemoved functions in sequence.
• removed RemovalMolecules, no longer needed.
• we now enforce with mutexes that instantation of molecule and MissedStateMap do not interfere, i.e. it is always perfectly clear whether to push a signal into the Map or whether to call the function of the present GLMolObj_mol.
• FIX: MoleculesInScene_mutex has not been used properly, now is.
• DOCU: Updated construct qt-gu documentation with the new concept.

File:

• src/documentation/constructs/qt-gui.dox (modified) (7 diffs)

src/documentation/constructs/qt-gui.dox

@@ -59 +59 @@
  * there is a QTimer that only updates an object in regular intervals, or
  * because of asynchronous threads. Elsewhen, the slot callback for a
- * certain signal is called directly. For all of these cases we have to
+ * certain signal is called directly. All of these cases we have to
  * accommodate. This is especially problematic with the instantiation and
- * destruction of objects.
+ * destruction of objects that represent atoms and molecules in the World.
  *
  * A clarifying example: Imagine an atom is constructed, the AtomObserver
@@ -70 +70 @@
  *
  * The only possible way out is to duplicate information. This is the usual
- * way how to deal with environments with multiple threads. I.e. all the
+ * way how to proceed in environments with multiple threads. I.e. all the
  * information that the GUI representants of information inside the World
  * needs to be doubled such that when the original information is destroyed
- * the representant can still be accessed as long as needed.
+ * the representant can still be accessed as long as needed. Here, we use
+ * the ObservedValue construct of CodePatterns.
  *
  * \subsection qt-gui-general-observedvalue Observed Value
@@ -100 +101 @@
  * pieces of information that require more computing resources within the
  * updater. Also, the Cacheable's information can only be obtained as long
- * as the source of information is still alive.
- *
- * Both concepts can be used in threaded environments as mutexed are used to
+ * as the source of information is still alive. However, so far Cacheable's
+ * content is marked invalid when an update signal has been received and
+ * update itself only on request, which is no longer possible when the object
+ * to represent is gone.
+ *
+ * Both concepts can be used in threaded environments as mutexes are used to
  * protect read and write accesses.
  *
- * \subsection qt-gui-general-signalslot Observer/Observable and Signal/Slot
- *
- * In the following we refer to Observer/Observable as "O/O" and to Signal/Slot
- * as "S/S".
- *
- * One thing we need to do is to translate between update() or
- * recieveNotification() calls from an Observable and subsequent signal/slot
- * calls. The general idea is to use these ObservedValues as translation
- * points for small pieces of information and Cacheables for larger pieces.
- *
- * However, we need more of these translation points:
- * -# GLWorldView checks for
- *   -# World's MoleculeInserted
- *   -# World's SelectionChanged
- *   -# WorldTime's TimeChanged
- *   -# each molecule's AtomInserted and AtomRemoved
- *   -# AtomObservable's AtomChanged.
- *   -# ShapeRegistry's ShapedAdded, ShapeRemoved, and SelectionChanged
- * -# GLMoleculeObject_molecule checks for
- *   -# molecule's AtomInserted, AtomRemoved, AtomMoved, IndexChanged
- *   -# World's SelectionChanged
- *
+ * \subsection qt-gui-general-observedinstance The observed instance board
+ *
+ * The setup is then as follows: We have two distinct realms, the World (with
+ * atoms and molecules) on the one side and the QtGUI (with visual
+ * representations of atoms and molecules) on the other side.
+ *
+ * There is an interface between this world such that the destruction of an
+ * atom does not directly invalidate its visual representation. This interface
+ * between the two realms is contained in the class QtObservedInstanceBoard,
+ * which is a singleton and is similar to the World instance in the World realm
+ * for the QtGui realm.
+ *
+ * All properties, e.g. the position of an element, relevant to the QtGUI are
+ * duplicated as ObservedValues. Properties associated to the same instance in
+ * the World, e.g. the same atom, are combined into a QtObservedAtom instance,
+ * and similarly QtObservedMolecule for molecule. All of these observed
+ * instances are placed into ObservedValuesContainer which are contained in
+ * the interface QtObservedInstanceBoard.
+ *
+ * The sequence of events is then as follows (here exemplified with an atom):
+ * -# an atom is created (World::createAtom()), the World notifies about it
+ *    via its World::AtomInserted channel.
+ * -# QtObservedInstanceBoard is signOn()ed to this channel and instantiates
+ *    a new QtObservedAtom which is placed into its respective
+ *    ObservedValuesContainer.
+ * -# on instantiation of QtObservedAtom a vector of specific ObservedValues is
+ *    created, one for each property (position, element, bond count, ...).
+ *    Each signOn()s to the respective atom's channel. Also the QtObservedAtom
+ *    signOn()s to each of these channels as it converts these notifications
+ *    into Qt signals (and the updated value can be accessed via getters from
+ *    the QtObservedAtom instance). The QtObservedInstanceBoard is notified
+ *    of this with the instance being marked as connected.
+ * -# when the atom is destroyed (World::destroyAtom()), being an Observable
+ *    it will call subjectKilled() on all its channels. The
+ *    ObservedValue_wCallback announces this subjectKilled() via the callback
+ *    function which notifies QtObservedAtom. Once all subjectKilled(), for
+ *    each observed value and for QtObservedAtom itself, have been received,
+ *    the QtObservedInstanceBoard is notified by the instance now being
+ *    marked as disconnected and ready for erase.
+ * -# then the QtObservedInstanceBoard removes the instance from its
+ *    ObservedValuesContainer.
+ *
+ * Note however that the instance is a shared_ptr and will continue to exist
+ * and therefore its getters will still deliver the last piece of information
+ * before the atom was destroyed until all shared_ptrs are released. Hence,
+ * the QtGui may safely continue using the pointer.
+ *
+ * As new observed instances may come in immediately having the same id and
+ * as it is difficult to keep track who got its observed instance already
+ * and who not, a soft fail is required. I.e. of the QtObservedInstanceBoard
+ * returns an empty shared_ptr this means that the object -- despite any
+ * received (and probably delayed) signal -- has been destroyed and should
+ * not be displayed, updated by, ... whatsoever.
+ *
+ * \subsection qt-gui-general-signalslot Details on the slot connections
+ *
+ * Qt's event system does not guarantee that events are always processed in
+ * the order they are emitted. This is because connections can be defined
+ * as direct or queued (or both with auto). Direct connections will always
+ * be executed as direct function calls, i.e. immediately. Queued connections
+ * however are inserted into Qt's event queue and may even get processed by
+ * a different thread.
+ *
+ * We have to take care of this.
+ *
+ * Basically what we do in QtObservedInstanceBoard and the observed instances
+ * of type QtObservedAtom and QtObservedMolecule is that we translate between
+ * the Observer/Observable (O/O) system of CodePatterns with its callback
+ * functions and the event system of Qt with its Signal/Slot (S/S).
+ *
+ * That is in the recieveNotification() functions many "emit()"s can be found.
+ *
+ * Furthermore, signals are used in a specific way to ensure synchronicity.
+ * This is only a problem with the visual representation as we there find a
+ * a nested problem: First molecules, then atoms belonging to a certain
+ * molecule. This enforces a certain sequence of events and thus of signals.
+ *
+ * \subsubsection qt-gui-general-signalslot-glworldscene Details on GLWorldScene
+ *
+ * The central place for all events is the GLWorldScene instance. There
+ * signals from QtObservedInstanceBoard for insertion and removal of both atoms
+ * and molecules are caught. Insertion of molecules is dealt with directly,
+ * we sign on to the inserted&removed channels for its atoms, then we emit
+ * a queued signal to actually instantiate the GLMoleculeObject_molecule.
+ *
+ * Until its instantiation we store incoming signals in the
+ * GLWorldScene::MoleculeMissedStateMap, protected by a mutex to enforce atomic
+ * access. After it has been instantiated (and all stored signals have been
+ * processed), they are relayed onto the specific instance. However, we do not
+ * do this via emits but by directly using Qt's invokeMethod() which allows
+ * to trigger queued events. This way it is done in a likewise manner whether
+ * it has been a stored or live signal that was received.
+ *
+ * \subsubsection qt-gui-general-signalslot-other Details on other signals
+ *
+ * All other signals that only change the property of a visual representation,
+ * e.g. the element of an atom, is directly processed by, in this case, the
+ * GLMoleculeObject_atom connected to QtObservedAtom.
+. *
  * \section qt-gui-qt3d Qt3D and the way to get atoms and bonds displayed
  *
@@ -146 +227 @@
  * of an element-specific color at the atom's position. The atom relies
  * on its representants to be contain all required information but it
- * is also signOn() to the atom itself whose O/O are translated to S/S
- * for processing whenever desired.
+ * is also signOn() to the QtObservedAtom itself whose O/O are translated to
+ * S/S for processing whenever desired.
  *
  * Next comes the GLMoleculeObject_bond which displays a cylinder between
@@ -158 +239 @@
  *
  * Parallel to these are GLMoleculeObject_shape which display the surface
- * of a selected shape. A shape in general does not change after instantation,
+ * of a selected shape. A shape in general does not change after instantiation,
  * hence the shape lives with the information it gets on instantiation till
  * it dies.
@@ -168 +249 @@
  * molecules. The molecule also needs ObservedValues for its bounding box
  * (used to show when it's selected), the index, the selection status,
- * and the list of atom ids. As Cacheable we use the tesselation structure.
+ * and the list of atom ids.
  *
  * \section qt-gui-cases Sample cases
@@ -270 +351 @@
  * they automatically clear the info box.
  *
- * \date 2015-07-15
+ * \date 2016-01-08
  */