1 files changed, 47 insertions, 0 deletions

diff --git a/src/sharedcore.h b/src/sharedcore.h
index ac36606..1887ca2 100644
--- a/src/sharedcore.h
+++ b/src/sharedcore.h
@@ -15,6 +15,53 @@
 
 namespace Bu
 {
+        /**
+         * 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
         {