Changeset 10aee4 for src/documentation

Timestamp:

Aug 5, 2015, 7:12:24 AM (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:

c307ba

Parents:

94232b

git-author:

Frederik Heber <heber@…> (08/03/15 09:25:02)

git-committer:

Frederik Heber <heber@…> (08/05/15 07:12:24)

Message:

Cleaned up ActionQueue's interface: Actions are always cloned.

• Action's dstor needs to be public as we have a clone() function.
• ActionRegistrys' (and AQ's) getActionByName now returns const ref. We must not return a ptr as it may not get deleted elsewhere. We are handing out prototypes.
• queueAction(action*,...) is private to prevent leakage, queueAction(string, ...) is the public interface.
• some other small functions are now private, too.
• MakroActions now need to clone() the prototype on prepare() and delete them on unprepare().
• ActionSequence deletes contained actions.
• FIX: ActionSequenceUnitTest cannot check on not-called property of removed actions anymore as these are gone now (they are deleted on removal and they are cloned on insertion).
• DOCU: Updated documentation on Actions.

File:

• src/documentation/constructs/actions.dox (modified) (3 diffs)

src/documentation/constructs/actions.dox

@@ -34 +34 @@
  *  If an Action is requested via its known token from the ActionQueue 
  *  (that contains the ActionRegistry), this prototype is cloned and added to the 
- *  queue.
+ *  queue. Action::clone() is a public function but only certain classes are
+ *  allowed to directly add Action instances to the ActionQueue. Normally, an
+ *  Action first has to be registered with the ActionRegistry and afterwards it
+ *  may be added to the queue via its specific and unique token.
  *
  *  Each Action can contain multiple \ref parameters in its specific 
@@ -56 +59 @@
  *    such that the ActionRegistry knows about it and can instantiate a
  *    prototype.
+ *
+ *  Most of the magic that fills in the remaining gaps of the Action's
+ *  declaration and definition is done by boost::preprocessor magic in the
+ *  files Action_impl_pre.hpp and Action_impl_header.hpp. There is a pendant
+ *  for MakroActions.
+ *
+ * \section actions-types Specific types of actions
+ *
+ *  There are some special types of Actions:
+ *  -# Calculation: A process with a final result that can be requested
+ *  -# MakroAction: A chain of other Actions to be executed various times
+ *  -# MethodAction: An action that basically calls a certain bound method
+ *  -# Process: An action that takes some time to complete and informs about
+ *     how much work remains
+ *
+ * \section actions-types-add Add a specific types of action ...
+ *
+ *  Instantiating the MakroAction is simple, only two functions, prepare()
+ *  and unprepare(), are required that fill und empty the chain of Actions
+ *  from Actions from the ActionRegistry.
+ *
+ *  Adding a Process is much the same as adding a normal Action. There is a
+ *  keyword BASECLASS in the associated \b .def file which should say Process
+ *  and one needs to use Process::setCurrStep(int) to tell the Process and
+ *  all listening Observers what the current stage of execution is. Also,
+ *  initially a total number of steps must be stated via Process::setMaxSteps()
+ *  When the job executes, this is initiated with Process::start() and when
+ *  it stops, this is told via Process::stop().
+ *
+ *  A Calculation must be derived by hand and is not supported via the
+ *  boost::preprocessor magic but behaves very similar to the Process itself
+ *  with respect to informing about the current stage of execution. What's
+ *  more is essentially the Calculation::doCalc() function that performs the
+ *  actual calculation (must not changed the state of the World and hence
+ *  there is not need for undo). The Calculation implementation takes care
+ *  of the rest.
+ *
+ *  A MethodAction is simply implemented by filling an ActionTraits structure
+ *  with the desired values and bind a method that should get executed.
+ *  Instantating the MethodAction with these parameters and executing
+ *  ActionRegistry()::registerAction() then allows for using it in the context
+ *  of the ActionQueue.
  *
  * \section actions-undo-redo Undoing and Redoing actions ...
@@ -81 +126 @@
  *
  *
- *  \date 2014-03-10
+ *  \date 2015-08-03
  *
  */