Changes in src/World.hpp [354859:24a5e0]

File:

• src/World.hpp (modified) (3 diffs)

src/World.hpp

@@ -9 +9 @@
 #define WORLD_HPP_
 
-#include <boost/thread.hpp>
+#include <string>
 #include <map>
 #include <vector>
 #include <set>
-
+#include <boost/thread.hpp>
+#include <boost/shared_ptr.hpp>
+
+#include "defs.hpp"
 #include "Patterns/Observer.hpp"
 #include "Patterns/Cacheable.hpp"
@@ -24 +27 @@
 class AtomDescriptor;
 class AtomDescriptor_impl;
+class ManipulateAtomsProcess;
+template<typename T>
+class AtomsCalculation;
 
 class World : public Observable
 {
+// necessary for coupling with descriptors
 friend class AtomDescriptor_impl;
+friend class AtomDescriptor;
+
+// Actions, calculations etc associated with the World
+friend class ManipulateAtomsProcess;
+template<typename> friend class AtomsCalculation;
 public:
+  typedef std::map<atomId_t,atom*> AtomSet;
+  typedef std::map<moleculeId_t,molecule*> MoleculeSet;
 
   /***** getter and setter *****/
   // reference to pointer is used for legacy reason... reference will be removed latter to keep encapsulation of World object
+  /**
+   * returns the periodentafel for the world.
+   */
   periodentafel *&getPeriode();
+
+  /**
+   * returns the first atom that matches a given descriptor.
+   * Do not rely on ordering for descriptors that match more than one atom.
+   */
   atom* getAtom(AtomDescriptor descriptor);
+
+  /**
+   * returns a vector containing all atoms that match a given descriptor
+   */
   std::vector<atom*> getAllAtoms(AtomDescriptor descriptor);
+  std::vector<atom*> getAllAtoms();
+
+  /**
+   * returns a calculation that calls a given function on all atoms matching a descriptor.
+   * the calculation is not called at this point and can be used as an action, i.e. be stored in
+   * menus, be kept around for later use etc.
+   */
+  template<typename T> AtomsCalculation<T>* calcOnAtoms(boost::function<T(atom*)>,std::string,AtomDescriptor);
+  template<typename T> AtomsCalculation<T>* calcOnAtoms(boost::function<T(atom*)>,std::string);
+
+  /**
+   * get the number of atoms in the World
+   */
   int numAtoms();
+
+  /**
+   * get the number of molecules in the World
+   */
   int numMolecules();
 
   /***** Methods to work with the World *****/
+
+  /**
+   * create a new molecule. This method should be used whenever any kind of molecule is needed. Assigns a unique
+   * ID to the molecule and stores it in the World for later retrieval. Do not create molecules directly.
+   */
   molecule *createMolecule();
+
+  void destroyMolecule(molecule*);
+  void destroyMolecule(moleculeId_t);
+
+  /**
+   * Create a new atom. This method should be used whenever any atom is needed. Assigns a unique ID and stores
+   * the atom in the World. If the atom is not destroyed it will automatically be destroyed when the world ends.
+   */
+  atom *createAtom();
+
+  /**
+   * Registers a Atom unknown to world. Needed in some rare cases, e.g. when cloning atoms, or in some unittests.
+   * Do not re-register Atoms already known to the world since this will cause double-frees.
+   */
+  int registerAtom(atom*);
+
+  /**
+     * Delete some atom and erase it from the world. Use this whenever you need to destroy any atom. Do not call delete on
+     * atom directly since this will leave the pointer inside the world.
+   */
+  void destroyAtom(atom*);
+
+  /**
+   * Delete some atom and erase it from the world. Use this whenever you need to destroy any atom. Do not call delete on
+   * atom directly since this will leave the pointer inside the world.
+   */
+  void destroyAtom(atomId_t);
+
+  /**
+   * Produces a process that calls a function on all Atoms matching a given descriptor. The process is not
+   * called at this time, so it can be passed around, stored inside menuItems etc.
+   */
+  ManipulateAtomsProcess* manipulateAtoms(boost::function<void(atom*)>,std::string,AtomDescriptor);
+  ManipulateAtomsProcess* manipulateAtoms(boost::function<void(atom*)>,std::string);
+
+protected:
+  /**** Iterators to use internal data structures */
+  class AtomIterator {
+  public:
+    AtomIterator();
+    AtomIterator(AtomDescriptor, World*);
+    AtomIterator(const AtomIterator&);
+    AtomIterator& operator=(const AtomIterator&);
+    AtomIterator& operator++();     // prefix
+    AtomIterator  operator++(int);  // postfix with dummy parameter
+    bool operator==(const AtomIterator&);
+    bool operator==(const AtomSet::iterator&);
+    bool operator!=(const AtomIterator&);
+    bool operator!=(const AtomSet::iterator&);
+    atom* operator*();
+
+    int getCount();
+  protected:
+    void advanceState();
+    AtomSet::iterator state;
+    boost::shared_ptr<AtomDescriptor_impl>  descr;
+    int index;
+
+    World* world;
+  };
+
+  /**
+   * returns an iterator over all Atoms matching a given descriptor.
+   * used for internal purposes, like AtomProcesses and AtomCalculations.
+   */
+  AtomIterator getAtomIter(AtomDescriptor descr);
+
+  /**
+   * returns an iterator to the end of the AtomSet. Due to overloading this iterator
+   * can be compared to iterators produced by getAtomIter (see the mis-matching types).
+   * Thus it can be used to detect when such an iterator is at the end of the list.
+   * used for internal purposes, like AtomProcesses and AtomCalculations.
+   */
+  AtomSet::iterator atomEnd();
+
+  /******* Internal manipulation routines for double callback and Observer mechanism ******/
+  void doManipulate(ManipulateAtomsProcess *);
+
 private:
   periodentafel *periode;
-  std::map<int,atom*> atoms;
-  std::set<molecule*> molecules;
+  AtomSet atoms;
+  atomId_t currAtomId; //!< stores the next available Id for atoms
+  MoleculeSet molecules;
+  moleculeId_t currMoleculeId;
 
 
   /***** singleton Stuff *****/
 public:
+
+  /**
+   * get the currently active instance of the World.
+   */
   static World* get();
+
+  /**
+   * destroy the currently active instance of the World.
+   */
   static void destroy();
+
+  /**
+   * destroy the currently active instance of the World and immidiately
+   * create a new one. Use this to reset while somebody is still Observing
+   * the world and should reset the observed instance. All observers will be
+   * sent the subjectKille() message from the old world.
+   */
   static World* reset();
 
 private:
+  /**
+   * private constructor to ensure creation of the world using
+   * the singleton pattern.
+   */
   World();
+
+  /**
+   * private destructor to ensure destruction of the world using the
+   * singleton pattern.
+   */
   virtual ~World();
 
@@ -68 +220 @@
   MoleculeListClass *&getMolecules();
 
-  // functions used for the WorldContent template mechanism
-  void registerAtom(atom *theAtom);
-  void unregisterAtom(atom *theAtom);
 private:
-  // this function cleans up anything that cannot be cleaned while the lock is active
-  // at a later point all these cleanups have to be moved to the World Class so the deadlock and
-  // race condition can both be avoided.
-  void destroyLegacy();
-
   MoleculeListClass *molecules_deprecated;
-
-  // this is needed to assign unique IDs to atoms... so far
-  // IDs are not assigned upon Atom creation, so we cannot query the ID
-  // during construction. By using the dummy ID we can make sure all atoms
-  // are actually stored in the map and don't overwrite each other.
-  int dummyId;
 };