gras: formalize the weak container api w/ docs

address issue #69, we now have a set_container call,
which is now formally part of the api.

Anyone can call set_container for custom container types.
GRAS supports shared ptr and pyobject out of the box.

6 files changed, 58 insertions, 36 deletions

diff --git a/include/gras/CMakeLists.txt b/include/gras/CMakeLists.txt
index 0ea4f2d..1ab9a4c 100644
--- a/include/gras/CMakeLists.txt
+++ b/include/gras/CMakeLists.txt
@@ -21,6 +21,7 @@ install(FILES
     top_block.hpp
     work_buffer.hpp
     buffer_queue.hpp
+    weak_container.hpp
 
     DESTINATION include/gras
     COMPONENT ${GRAS_COMP_DEVEL}
diff --git a/include/gras/detail/element.hpp b/include/gras/detail/element.hpp
index f8a8904..8d3e20e 100644
--- a/include/gras/detail/element.hpp
+++ b/include/gras/detail/element.hpp
@@ -9,9 +9,9 @@ namespace gras
 {
 
     //! Weak element overload for the case of shared_ptr container
-    struct WeakElementSharedPtr : WeakElement
+    struct WeakContainerSharedPtr : WeakContainer
     {
-        WeakElementSharedPtr(boost::weak_ptr<const void> weak_self)
+        WeakContainerSharedPtr(boost::weak_ptr<const void> weak_self)
         {
             _weak_self = weak_self;
         }
@@ -25,12 +25,8 @@ namespace gras
     template <typename T>
     inline Element::Element(const boost::shared_ptr<T> &elem)
     {
-        //the container is a shared pointer, so save the reference,
-        //unless the reference was already set to something
-        if (not elem->weak_self)
-        {
-            elem->weak_self.reset(new WeakElementSharedPtr(elem));
-        }
+        //the container is a shared pointer, so save the reference
+        elem->set_container(new WeakContainerSharedPtr(elem));
 
         //initialize this new Element from the argument passed
         *this = *elem;
diff --git a/include/gras/element.hpp b/include/gras/element.hpp
index 78af403..0aed924 100644
--- a/include/gras/element.hpp
+++ b/include/gras/element.hpp
@@ -9,32 +9,16 @@
 #endif //_MSC_VER
 
 #include <gras/gras.hpp>
+#include <gras/weak_container.hpp>
 #include <boost/shared_ptr.hpp>
 
 namespace gras
 {
 
-struct ElementImpl;
-
-typedef boost::shared_ptr<ElementImpl> ElementBase;
-
-struct Block;
-
-/*!
- * Weak Element interface class:
- * Allows internals to get a reference to the container holding an element.
- * This container could be a shared_ptr or perhaps a Python object.
- */
-struct WeakElement
-{
-    //! Lock creates a shared pointer holding a container reference
-    virtual boost::shared_ptr<const void> lock(void) = 0;
-};
-
 /*!
  * Element is a base class for all topological elements.
  */
-struct GRAS_API Element : ElementBase
+struct GRAS_API Element : boost::shared_ptr<ElementImpl>
 {
     //! Create an empty element
     Element(void);
@@ -58,6 +42,15 @@ struct GRAS_API Element : ElementBase
     Element &to_element(void);
 
     /*!
+     * Set a reference wrapper for the parent container to this element.
+     * Allows internals to get a reference to the container holding an element.
+     * The actual container could be a shared_ptr or perhaps a Python object.
+     * Note: the container parameter is assumed to be allocated with new.
+     * The element object will be responsible for deleting container.
+     */
+    void set_container(WeakContainer *container);
+
+    /*!
      * Check if another element is the same as this one.
      * \return true if the rhs is the same as *this.
      */
@@ -105,16 +98,6 @@ struct GRAS_API Element : ElementBase
      */
     Block *locate_block(const std::string &path);
 
-    /*******************************************************************
-     * API for dealing with parent containers - for internal use
-     ******************************************************************/
-
-    /*!
-     * Allows internals to get a reference to the container holding an element.
-     * This container could be a shared_ptr or perhaps a Python object.
-     */
-    boost::shared_ptr<WeakElement> weak_self;
-
 };
 
 } //namespace gras
diff --git a/include/gras/element.i b/include/gras/element.i
index 8f04a3d..ecfa898 100644
--- a/include/gras/element.i
+++ b/include/gras/element.i
@@ -7,6 +7,11 @@
 #include <gras/element.hpp>
 %}
 
+namespace gras
+{
+    %ignore Element::set_container;
+}
+
 ////////////////////////////////////////////////////////////////////////
 // remove base class warning
 ////////////////////////////////////////////////////////////////////////
diff --git a/include/gras/gras.hpp b/include/gras/gras.hpp
index 6d1808b..c809f45 100644
--- a/include/gras/gras.hpp
+++ b/include/gras/gras.hpp
@@ -70,6 +70,12 @@ namespace gras
 {
     //! Typedef for absolute item indexes
     typedef unsigned long long item_index_t;
+
+    //! Forward declare for element base class
+    struct ElementImpl;
+
+    //! Forward declare for block class
+    struct Block;
 }
 
 #endif /*INCLUDED_GRAS_GRAS_HPP*/
diff --git a/include/gras/weak_container.hpp b/include/gras/weak_container.hpp
new file mode 100644
index 0000000..e2bc560
--- /dev/null
+++ b/include/gras/weak_container.hpp
@@ -0,0 +1,31 @@
+// Copyright (C) by Josh Blum. See LICENSE.txt for licensing information.
+
+#ifndef INCLUDED_GRAS_WEAK_CONTAINER_HPP
+#define INCLUDED_GRAS_WEAK_CONTAINER_HPP
+
+#include <gras/gras.hpp>
+#include <boost/shared_ptr.hpp>
+
+namespace gras
+{
+
+    /*!
+     * Weak Container interface class:
+     * A weak container is an object with a method called lock.
+     * Lock gets a reference to an object's parent container.
+     * The weak container itself does not actually hold a reference.
+     * This container class is shared_ptr, a Pyobject, anything.
+     */
+    struct GRAS_API WeakContainer
+    {
+        WeakContainer(void);
+
+        virtual ~WeakContainer(void);
+
+        //! Lock creates a shared pointer holding a container reference
+        virtual boost::shared_ptr<const void> lock(void) = 0;
+    };
+
+} //namespace gras
+
+#endif /*INCLUDED_GRAS_WEAK_CONTAINER_HPP*/