Index: src/Actions/ActionQueue.cpp
===================================================================
--- src/Actions/ActionQueue.cpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/Actions/ActionQueue.cpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -42,4 +42,6 @@
 #include "CodePatterns/Singleton_impl.hpp"
 
+#include <boost/date_time/posix_time/posix_time.hpp>
+#include <boost/version.hpp>
 #include <string>
 #include <sstream>
@@ -56,9 +58,13 @@
     AR(new ActionRegistry()),
     history(new ActionHistory),
-    CurrentAction(0)
+    CurrentAction(0),
+    run_thread(boost::bind(&ActionQueue::run, this)),
+    run_thread_isIdle(true)
 {}
 
 ActionQueue::~ActionQueue()
 {
+  stop();
+
   // free all actions contained in actionqueue
   for (ActionQueue_t::iterator iter = actionqueue.begin(); !actionqueue.empty(); iter = actionqueue.begin()) {
@@ -80,16 +86,101 @@
   Action *newaction = _action->clone(state);
   newaction->prepare(state);
+  mtx_queue.lock();
   actionqueue.push_back( newaction );
-  try {
-    newaction->call();
-  } catch(ActionFailureException &e) {
-    std::cerr << "Action " << *boost::get_error_info<ActionNameString>(e) << " has failed." << std::endl;
-    World::getInstance().setExitFlag(5);
-  }
+  {
+    boost::lock_guard<boost::mutex> lock(mtx_idle);
+    run_thread_isIdle = (CurrentAction == actionqueue.size());
+  }
+  mtx_queue.unlock();
 }
 
 void ActionQueue::insertAction(Action *_action, enum Action::QueryOptions state)
 {
-  queueAction(_action, state);
+  Action *newaction = _action->clone(state);
+  newaction->prepare(state);
+  mtx_queue.lock();
+  tempqueue.push_back( newaction );
+  {
+    boost::lock_guard<boost::mutex> lock(mtx_idle);
+    run_thread_isIdle = !((CurrentAction != actionqueue.size()) || !tempqueue.empty());
+  }
+  mtx_queue.unlock();
+}
+
+void ActionQueue::run()
+{
+  bool Interrupted = false;
+  do {
+    // sleep for some time and wait for queue to fill up again
+    try {
+#if BOOST_VERSION < 105000
+      run_thread.sleep(boost::get_system_time() + boost::posix_time::milliseconds(100));
+#else
+      run_thread.sleep_for(100);
+#endif
+    } catch(boost::thread_interrupted &e) {
+      LOG(2, "INFO: ActionQueue has received stop signal.");
+      Interrupted = true;
+    }
+//    LOG(1, "DEBUG: Start of ActionQueue's run() loop.");
+    // call all currently present Actions
+    mtx_queue.lock();
+    insertTempQueue();
+    bool status = (CurrentAction != actionqueue.size());
+    mtx_queue.unlock();
+    while (status) {
+      //      boost::this_thread::disable_interruption di;
+      LOG(0, "Calling Action " << actionqueue[CurrentAction]->getName() << " ... ");
+      try {
+        actionqueue[CurrentAction]->call();
+      } catch(ActionFailureException &e) {
+        std::cerr << "Action " << *boost::get_error_info<ActionNameString>(e) << " has failed." << std::endl;
+        World::getInstance().setExitFlag(5);
+      }
+      // access actionqueue, hence using mutex
+      mtx_queue.lock();
+      // step on to next action and check for end
+      CurrentAction++;
+      // insert new actions (before [CurrentAction]) if they have been spawned
+      // we must have an extra vector for this, as we cannot change actionqueue
+      // while an action instance is "in-use"
+      insertTempQueue();
+      status = (CurrentAction != actionqueue.size());
+      mtx_queue.unlock();
+    }
+    {
+      boost::lock_guard<boost::mutex> lock(mtx_idle);
+      run_thread_isIdle = !((CurrentAction != actionqueue.size()) || !tempqueue.empty());
+    }
+    cond_idle.notify_one();
+//    LOG(1, "DEBUG: End of ActionQueue's run() loop.");
+  } while (!Interrupted);
+}
+
+void ActionQueue::insertTempQueue()
+{
+  if (!tempqueue.empty()) {
+    ActionQueue_t::iterator InsertionIter = actionqueue.begin();
+    std::advance(InsertionIter, CurrentAction);
+    actionqueue.insert( InsertionIter, tempqueue.begin(), tempqueue.end() );
+    tempqueue.clear();
+  }
+}
+
+void ActionQueue::wait()
+{
+  boost::unique_lock<boost::mutex> lock(mtx_idle);
+  while(!run_thread_isIdle)
+  {
+      cond_idle.wait(lock);
+  }
+}
+
+void ActionQueue::stop()
+{
+  // notify actionqueue thread that we wish to terminate
+  run_thread.interrupt();
+  // wait till it ends
+  run_thread.join();
 }
 
Index: src/Actions/ActionQueue.hpp
===================================================================
--- src/Actions/ActionQueue.hpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/Actions/ActionQueue.hpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -16,8 +16,12 @@
 #include "CodePatterns/Singleton.hpp"
 
+#include <boost/thread.hpp>
 #include <vector>
 
 #include "Actions/Action.hpp"
 #include "Actions/ActionState.hpp"
+
+void stopQueue();
+void waitQueue();
 
 namespace MoleCuilder {
@@ -113,14 +117,6 @@
   void redoLast();
 
-  /** Getter for the last executed action.
-   *
-   * \note this is necessary for Reactions to actually have a chance of getting
-   * the calculated value as Action's are always cloned.
-   *
-   * \return const ref to last action
-   */
-  const Action &getLastAction() const {
-    return *(actionqueue.back());
-  }
+  boost::thread &getRunThread()
+  { return run_thread; }
 
 private:
@@ -140,4 +136,23 @@
   void clear();
 
+  /** Runs the ActionQueue.
+   *
+   */
+  void run();
+
+  friend void ::stopQueue();
+
+  /** Stops the internal thread.
+   *
+   */
+  void stop();
+
+  friend void ::waitQueue();
+
+  /** Wait till all currently queued actions are processed.
+   *
+   */
+  void wait();
+
   /** Insert an action after CurrentAction.
    *
@@ -148,4 +163,9 @@
   void insertAction(Action *_action, enum Action::QueryOptions state);
 
+  /** Moves all action from tempqueue into real queue.
+   *
+   */
+  void insertTempQueue();
+
 private:
   /** Private cstor for ActionQueue.
@@ -172,4 +192,22 @@
   //!> point to current action in actionqueue
   size_t CurrentAction;
+
+  //!> internal temporary actionqueue of actions used by insertAction()
+  ActionQueue_t tempqueue;
+
+  //!> internal thread to call Actions
+  boost::thread run_thread;
+
+  //!> internal mutex to synchronize access to queue
+  boost::mutex mtx_queue;
+
+  //!> conditional variable notifying when run_thread is idling
+  boost::condition_variable cond_idle;
+
+  //!> flag indicating whether run_thread is idle or not
+  bool run_thread_isIdle;
+
+  //!> internal mutex to synchronize access to run_thread_isIdle
+  boost::mutex mtx_idle;
 };
 
Index: src/Python/Makefile.am
===================================================================
--- src/Python/Makefile.am	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/Python/Makefile.am	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -8,5 +8,6 @@
 	Python/getSelectedMolarMass.cpp \
 	Python/PythonScripting.cpp \
-	Python/reinit.cpp
+	Python/reinit.cpp \
+	Python/wait.cpp
 				  
 PYTHONHEADER = \
Index: src/Python/PythonScripting_impl.hpp
===================================================================
--- src/Python/PythonScripting_impl.hpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/Python/PythonScripting_impl.hpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -85,4 +85,9 @@
       "Reinitializes the internal state of the python module as if it had been freshly imported,saves all input files beforehand."
   );
+  boost::python::def(
+      "wait",
+      MoleCuilder::detail::module_wait,
+      "Waits until all currently queued actions have been processed."
+  );
   boost::python::def< MoleCuilder::detail::doubleVec() >(
       "getBoundingBox",
Index: src/Python/wait.cpp
===================================================================
--- src/Python/wait.cpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
+++ src/Python/wait.cpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -0,0 +1,51 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2013 Frederik Heber. All rights reserved.
+ * 
+ *
+ *   This file is part of MoleCuilder.
+ *
+ *    MoleCuilder is free software: you can redistribute it and/or modify
+ *    it under the terms of the GNU General Public License as published by
+ *    the Free Software Foundation, either version 2 of the License, or
+ *    (at your option) any later version.
+ *
+ *    MoleCuilder is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *    GNU General Public License for more details.
+ *
+ *    You should have received a copy of the GNU General Public License
+ *    along with MoleCuilder.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/*
+ * wait.cpp
+ *
+ *  Created on: Sep 28, 2013
+ *      Author: heber
+ */
+
+// include config.h
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include "CodePatterns/MemDebug.hpp"
+
+#include "modules.hpp"
+
+#include "CodePatterns/Log.hpp"
+
+#include "UIElements/UIFactory.hpp"
+#include "cleanUp.hpp"
+
+void MoleCuilder::detail::module_wait()
+{
+  // prevent wait() in python scripts in case of present UI (loaded sessions)
+  if (!UIFactory::isFactoryPresent()) {
+    LOG(0, "Waiting for action queue to idle.");
+    waitQueue();
+  }
+}
Index: src/UIElements/UIFactory.hpp
===================================================================
--- src/UIElements/UIFactory.hpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/UIElements/UIFactory.hpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -77,4 +77,5 @@
   static void makeUserInterface(std::string type);
   static void registerFactory(factoryDescription *factoryDesc);
+  static bool isFactoryPresent() { return !factories.empty(); }
   virtual std::string getUIName(){  return "none";  }
 protected:
Index: src/builder.cpp
===================================================================
--- src/builder.cpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/builder.cpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -49,4 +49,6 @@
   doUI();
 
+  waitQueue();
+  stopQueue();
   if (UIFactory::getInstance().getUIName() == "CommandLine")
     return saveAll();
Index: src/builder_init.hpp
===================================================================
--- src/builder_init.hpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/builder_init.hpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -20,4 +20,3 @@
 void doUI();
 
-
 #endif /* BUILDER_INIT_HPP_ */
Index: src/cleanUp.cpp
===================================================================
--- src/cleanUp.cpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/cleanUp.cpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -92,4 +92,6 @@
 void purgeStaticInstances()
 {
+  // make sure that ActionQueue is already purged!
+
   Chronos::purgeInstance();
   RandomNumberDistributionFactory::purgeInstance();
@@ -105,6 +107,4 @@
   UIFactory::purgeInstance();
   CommandLineParser::purgeInstance();
-  MoleCuilder::ActionQueue::purgeInstance();
-  MoleCuilder::OptionRegistry::purgeInstance();
   logger::purgeInstance();
   errorLogger::purgeInstance();
@@ -112,13 +112,27 @@
 }
 
+void stopAndPurgeQueue()
+{
+  // adding a wait here such that ActionQueue's run_thread is done any may stop
+  waitQueue();
+  MoleCuilder::ActionQueue::purgeInstance();
+  MoleCuilder::OptionRegistry::purgeInstance();
+}
+
+void printTimings(const MoleCuilder::ActionQueue::ActionTokens_t &tokens);
+
 /** Cleans all singleton instances in an orderly fashion.
  * C++ does not guarantee any specific sequence of removal of single instances
  * which have static/global variables. Some singletons depend on others hence we
- * acertain a specific ordering here, which is is used via the atexit() hook.
+ * ascertain a specific ordering here, which is is used via the atexit() hook.
  */
 void cleanUp()
 {
-  // give timings per Action
-  printTimings();
+  // stop queue
+  const MoleCuilder::ActionQueue::ActionTokens_t tokens = MoleCuilder::ActionQueue::getInstance().getListOfActions();
+  stopAndPurgeQueue();
+  // give timings per Action, requires still present Chronos
+  printTimings(tokens);
+
   // purge static instances from memory
   purgeStaticInstances(); 
@@ -138,8 +152,13 @@
 /** We give a list of all times per action and a total time.
  *
- */
-void printTimings()
-{
-  const MoleCuilder::ActionQueue::ActionTokens_t tokens = MoleCuilder::ActionQueue::getInstance().getListOfActions();
+ * We require a list of Action tokens such that we do not access the ActionQueue.
+ * Timings are printed when Actions have all been performed, hence the queue should
+ * already be purged and we cannot access it anymore.
+ *
+ * \param tokens
+ */
+void printTimings(const MoleCuilder::ActionQueue::ActionTokens_t &tokens)
+{
+//  const MoleCuilder::ActionQueue::ActionTokens_t tokens = MoleCuilder::ActionQueue::getInstance().getListOfActions();
   const Chronos &Chron = Chronos::getInstance();
   if (!DoLog(2)) {
@@ -198,2 +217,18 @@
   return (ExitFlag == 1 ? 0 : ExitFlag);
 }
+
+/** Stops the queue such that all Actions are done.
+ *
+ */
+void stopQueue()
+{
+  MoleCuilder::ActionQueue::getInstance().stop();
+}
+
+/** Waits for the queue to idle.
+ *
+ */
+void waitQueue()
+{
+  MoleCuilder::ActionQueue::getInstance().wait();
+}
Index: src/cleanUp.hpp
===================================================================
--- src/cleanUp.hpp	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/cleanUp.hpp	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -17,7 +17,8 @@
 void cleanUp();
 void dumpMemory();
-void printTimings();
 void purgeStaticInstances();
 int saveAll();
+void stopQueue();
+void waitQueue();
 
 #endif /* CLEANUP_HPP_ */
Index: src/documentation/Makefile.am
===================================================================
--- src/documentation/Makefile.am	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/documentation/Makefile.am	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -13,4 +13,5 @@
 	${top_srcdir}/src/documentation/constructs/constructs.dox \
 	${top_srcdir}/src/documentation/constructs/descriptors.dox \
+	${top_srcdir}/src/documentation/constructs/filling.dox \
 	${top_srcdir}/src/documentation/constructs/fragmentation.dox \
 	${top_srcdir}/src/documentation/constructs/linearalgebra.dox \
@@ -18,9 +19,16 @@
 	${top_srcdir}/src/documentation/constructs/molecules.dox \
 	${top_srcdir}/src/documentation/constructs/observers_observables.dox \
+	${top_srcdir}/src/documentation/constructs/parameters.dox \
 	${top_srcdir}/src/documentation/constructs/parsers.dox \
+	${top_srcdir}/src/documentation/constructs/potentials.dox \
+	${top_srcdir}/src/documentation/constructs/qt-gui.dox \
+	${top_srcdir}/src/documentation/constructs/queries.dox \
 	${top_srcdir}/src/documentation/constructs/randomnumbers.dox \
 	${top_srcdir}/src/documentation/constructs/serialization.dox \
+	${top_srcdir}/src/documentation/constructs/shaperegistry.dox \
 	${top_srcdir}/src/documentation/constructs/shapes.dox \
 	${top_srcdir}/src/documentation/constructs/tesselation.dox \
+	${top_srcdir}/src/documentation/constructs/validators.dox \
+	${top_srcdir}/src/documentation/constructs/values.dox \
 	${top_srcdir}/src/documentation/constructs/world.dox \
 	${top_srcdir}/src/documentation/howtos/action.dox \
Index: src/documentation/userinterfaces/python.dox
===================================================================
--- src/documentation/userinterfaces/python.dox	(revision 975b83561278df8e9f4dc52a379883b4c726b00e)
+++ src/documentation/userinterfaces/python.dox	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -20,5 +20,5 @@
  *  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,7 +43,23 @@
  *  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,4 +88,5 @@
  *  \code
  *  pyMoleCuilder.WorldInput("test.xyz")
+ *  pyMoleCuilder.wait()
  *  \endcode
  *
@@ -78,4 +95,5 @@
  *  \code
  *  pyMoleCuilder.SelectionAllMolecules()
+ *  pyMoleCuilder.wait()
  *  \endcode
  *
@@ -84,5 +102,13 @@
  *  \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,6 +141,23 @@
  *  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
  *
  */
