1 files changed, 75 insertions, 2 deletions

diff --git a/src/sharedcore.h b/src/sharedcore.h
index 5a44df9..1887ca2 100644
--- a/src/sharedcore.h
+++ b/src/sharedcore.h
@@ -15,10 +15,57 @@
 
 namespace Bu
 {
-        template<typename Core>
+        /**
+         * A mechanism for creating classes that perform lazy copies.  The concept
+         * behind this is that instead of copying a large object when it is assigned
+         * or passed into a copy constructor we simply copy a pointer internally.
+         * The assumption is that many times when an object is passed by value we
+         * don't really want to keep the object around, we want the recipient to
+         * take ownership without allocating a new object.  This allows that to
+         * happen.
+         *
+         * When used properly this makes object copying essentially free (O(1),
+         * that is) and performs the actual copy when a user tries to modify the
+         * object.
+         *
+         * For example, lets look at something like the getKeys function in
+         * Bu::Hash.  When this function is called it creates a Bu::List of
+         * appropriate type, fills it with keys, and returns it.  This is a good
+         * way for this function to behave, there may be additional issues if the
+         * List object were allocated with new and not on the stack.  However,
+         * returning the List at the end of the function could potentially take
+         * a very long time depending on the size of the list and the type of the
+         * key.  In this case the getKeys function doesn't want ownership of the
+         * List object, and when it returns it, it's local copy will be destroyed.
+         *
+         * However, List inherits from SharedCore, which means that when it is
+         * returned all we do is copy a pointer to the "core" of the list, which
+         * is a very fast operatorion.  For a brief moment, before anyone can do
+         * anything else, there are two objects referencing the core of that single
+         * list.  However, the getKeys() function will destroy it's local copy
+         * before the calling function can use it's new copy.  That means that by
+         * the time the calling function can use it's new List of keys it is the
+         * only one with a reference to the core, and no copy will need to happen.
+         *
+         * Using SharedCore on your own classes is fairly straight forward.  There
+         * are only a couple of steps.  First, break the class into two classes.
+         * Move every variable from the original class (generally everything that's
+         * private) into the new class.  Then make the original class inherit from
+         * SharedCore.  The SharedCore template takes 2 parameters, first is the
+         * class it's inheriting from, second is the new core class.  Now, in your
+         * original class you will have one class variable, a pointer named core.
+         * All of your original variables will be accessable through core.  The next
+         * step is to access everything you used to through core, and to find 
+         * every function that may change data in the core.  At the top of every
+         * function that may change data you want to call _hardCopy().
+         *
+         * That's more or less it.  A more detailed guide will be written soon.
+         * @todo Write a guide for this.
+         */
+        template<typename Shell, typename Core>
         class SharedCore
         {
-                typedef class SharedCore<Core> _SharedType;
+                typedef class SharedCore<Shell, Core> _SharedType;
         public:
                 SharedCore() :
                         core( NULL ),
@@ -54,6 +101,18 @@ namespace Bu
                         return *iRefCount;
                 }
 
+                Shell clone() const
+                {
+                        Shell s( dynamic_cast<const Shell &>(*this) );
+                        s._hardCopy();
+                        return s;
+                }
+
+                bool isCoreShared( const Shell &rOther ) const
+                {
+                        return rOther.core == core;
+                }
+
         protected:
                 Core *core;
                 void _hardCopy()
@@ -68,6 +127,20 @@ namespace Bu
                         iRefCount = new int( 1 );
                 }
 
+                /**
+                 * Reset core acts like a hard copy, except instead of providing a
+                 * standalone copy of the shared core, it provides a brand new core.
+                 *
+                 * Very useful in functions used to reset the state of an object.
+                 */
+                void _resetCore()
+                {
+                        if( core )
+                                _deref();
+                        core = _allocateCore();
+                        iRefCount = new int( 1 );
+                }
+
                 virtual Core *_allocateCore()
                 {
                         return new Core();