Documented ContextManager

library/DFContextManager.cpp

@@ -130,6 +130,13 @@ ContextManager::ContextManager (const string path_to_xml) : d (new Private())
 ContextManager::~ContextManager()
 {
     purge();
+    // process enumerator has to be destroyed after we detach from processes
+    // because it tracks and destroys them
+    if(d->pEnum)
+    {
+        delete d->pEnum;
+        d->pEnum = 0;
+    }
     delete d;
 }
 
@@ -174,7 +181,6 @@ uint32_t ContextManager::Refresh( BadContexts* bad_contexts )
         // no expired contexts are in the d->contexts vector now
         // all processes remaining in 'expired' are now destroyed along with it
     }
-    
     int numProcesses = d->pEnum->size();
     int numContexts = d->contexts.size();
     vector <Context *> newContexts;
@@ -207,12 +213,14 @@ uint32_t ContextManager::size()
 {
     return d->contexts.size();
 }
+
 Context * ContextManager::operator[](uint32_t index)
 {
     if (index < d->contexts.size())
         return d->contexts[index];
     return 0;
 }
+
 Context * ContextManager::getSingleContext()
 {
     if(!d->contexts.size())
@@ -228,16 +236,11 @@ Context * ContextManager::getSingleContext()
     }
     throw DFHack::Error::NoProcess();
 }
+
 void ContextManager::purge(void)
 {
     for(int i = 0; i < d->contexts.size();i++)
         delete d->contexts[i];
     d->contexts.clear();
-    // process enumerator has to be destroyed after we detach from processes
+    d->pEnum->purge();
-    // because it tracks and destroys them
-    if(d->pEnum)
-    {
-        delete d->pEnum;
-        d->pEnum = 0;
-    }
 }

library/include/dfhack/DFContextManager.h

@@ -37,33 +37,106 @@ namespace DFHack
     class Context;
     class BadContexts;
     class Process;
-
+    /**
+     * Used to enumerate, create and destroy Contexts. The very base of DFHack.
+     * @see DFHack::Context
+     */
     class DFHACK_EXPORT ContextManager
     {
         class Private;
         Private * const d;
     public:
+        /**
+        * Constructs the ContextManager.
+        * @param path_to_xml the path to the file that defines memory offsets. (Memory.xml)
+        */
         ContextManager(const std::string path_to_xml);
+
+        /**
+        * Destroys the ContextManager.
+        */
         ~ContextManager();
+
+        /**
+        * Refresh the internal list of valid Context objects.
+        * @param bad_contexts pointer to a BadContexts object. Not required. All contexts are automatically destroyed if the object is not provided.
+        * @see DFHack::BadContexts
+        * @return Number of tracked contexts
+        */
         uint32_t Refresh(BadContexts* bad_contexts = 0);
+
+        /**
+        * Get the number of tracked contexts.
+        * @return Number of tracked contexts
+        */
         uint32_t size();
+
+        /**
+        * Get a context by index
+        * @param index index of the context to be returned
+        * @return pointer to a Context
+        */
         Context * operator[](uint32_t index);
+
+        /**
+        * Convenience method to return a single valid Context
+        * @return pointer to a Context
+        */
         Context * getSingleContext();
+
+        /**
+        * Destroy all tracked Context objects
+        * Normally called during object destruction. Calling this from outside ContextManager is nasty.
+        */
         void purge(void);
     };
+
+    /**
+     * Class used for holding a set of invalidated Context AND Process objects temporarily and destroy them safely.
+     * @see DFHack::Context
+     * @see DFHack::Process
+     */
     class DFHACK_EXPORT BadContexts
     {
         class Private;
         Private * const d;
         void push_back(Context * c);
         friend class ContextManager;
+        void clear();
     public:
         BadContexts();
+        /**
+        * Destructor.
+        * All Processes and Contexts tracked by the BadContexts object will be destroyed also.
+        */
         ~BadContexts();
+
+        /**
+        * Test if a Context is among the invalidated Contexts
+        * @param c pointer to a Context to be checked
+        * @return true if the Context is among the invalidated. false otherwise.
+        */
         bool Contains(Context* c);
+
+        /**
+        * Test if a Process is among the invalidated Processes/Contexts
+        * @param p pointer to a Process to be checked
+        * @see DFHack::Process
+        * @return true if the Process is among the invalidated. false otherwise.
+        */
         bool Contains(Process* p);
+
+        /**
+        * Get the number of tracked invalid contexts.
+        * @return Number of tracked invalid contexts
+        */
         uint32_t size();
-        void clear();
+
+        /**
+        * Get an invalid Context by index
+        * @param index index of the invalid Context to be returned
+        * @return pointer to an invalid Context
+        */
         Context * operator[](uint32_t index);
     };
 } // namespace DFHack