Engine directory for ticket #1

Engine/source/console/simSet.h

@@ -0,0 +1,464 @@
+//-----------------------------------------------------------------------------
+// Copyright (c) 2012 GarageGames, LLC
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+//-----------------------------------------------------------------------------
+
+#ifndef _SIMSET_H_
+#define _SIMSET_H_
+
+#ifndef _SIMOBJECT_H_
+#include "console/simObject.h"
+#endif
+
+#ifndef _SIMOBJECTLIST_H_
+#include "console/simObjectList.h"
+#endif
+
+#ifndef _SIMDICTIONARY_H_
+#include "console/simDictionary.h"
+#endif
+
+#ifndef _TSIGNAL_H_
+#include "core/util/tSignal.h"
+#endif
+
+
+//---------------------------------------------------------------------------
+/// A set of SimObjects.
+///
+/// It is often necessary to keep track of an arbitrary set of SimObjects.
+/// For instance, Torque's networking code needs to not only keep track of
+/// the set of objects which need to be ghosted, but also the set of objects
+/// which must <i>always</i> be ghosted. It does this by working with two
+/// sets. The first of these is the RootGroup (which is actually a SimGroup)
+/// and the second is the GhostAlwaysSet, which contains objects which must
+/// always be ghosted to the client.
+///
+/// Some general notes on SimSets:
+///     - Membership is not exclusive. A SimObject may be a member of multiple
+///       SimSets.
+///     - A SimSet does not destroy subobjects when it is destroyed.
+///     - A SimSet may hold an arbitrary number of objects.
+///
+/// Using SimSets, the code to work with these two sets becomes
+/// relatively straightforward:
+///
+/// @code
+///        // (Example from netObject.cc)
+///        // To iterate over all the objects in the Sim:
+///        for (SimSetIterator obj(Sim::getRootGroup()); *obj; ++obj)
+///        {
+///                  NetObject* nobj = dynamic_cast<NetObject*>(*obj);
+///
+///                 if (nobj)
+///                   {
+///                     // ... do things ...
+///                 }
+///         }
+///
+///         // (Example from netGhost.cc)
+///         // To iterate over the ghostAlways set.
+///         SimSet* ghostAlwaysSet = Sim::getGhostAlwaysSet();
+///         SimSet::iterator i;
+///
+///         U32 sz = ghostAlwaysSet->size();
+///         S32 j;
+///
+///         for(i = ghostAlwaysSet->begin(); i != ghostAlwaysSet->end(); i++)
+///         {
+///             NetObject *obj = (NetObject *)(*i);
+///
+///             /// ... do things with obj...
+///         }
+/// @endcode
+///
+class SimSet: public SimObject
+{
+   public:
+
+      typedef SimObject Parent;
+
+      enum SetModification
+      {
+         SetCleared,
+         SetObjectAdded,
+         SetObjectRemoved
+      };
+
+      /// Signal for letting observers know when objects are added to or removed from
+      /// the set.
+      ///
+      /// @param modification In what way the set has been modified.
+      /// @param set The set that has been modified.
+      /// @param object If #modification is #SetObjectAdded or #SetObjectRemoved, this is
+      ///   the object that has been added or removed.  Otherwise NULL.
+      typedef Signal< void( SetModification modification, SimSet* set, SimObject* object ) > SetModificationSignal;
+
+   protected:
+
+      SimObjectList objectList;
+      void *mMutex;
+
+      /// Signal that is triggered when objects are added or removed from the set.
+      SetModificationSignal mSetModificationSignal;
+      
+      /// @name Callbacks
+      /// @{
+      
+      DECLARE_CALLBACK( void, onObjectAdded, ( SimObject* object ) );
+      DECLARE_CALLBACK( void, onObjectRemoved, ( SimObject* object ) );
+      
+      /// @}
+
+   public:
+
+      SimSet();
+      ~SimSet();
+
+      /// Return the signal that is triggered when an object is added to or removed
+      /// from the set.
+      const SetModificationSignal& getSetModificationSignal() const { return mSetModificationSignal; }
+      SetModificationSignal& getSetModificationSignal() { return mSetModificationSignal; }
+
+      /// @name STL Interface
+      /// @{
+
+      ///
+      typedef SimObjectList::iterator iterator;
+      typedef SimObjectList::value_type value;
+      SimObject* front() { return objectList.front(); }
+      SimObject* first() { return objectList.first(); }
+      SimObject* last()  { return objectList.last(); }
+      bool       empty() const { return objectList.empty();   }
+      S32        size() const  { return objectList.size(); }
+      iterator   begin() { return objectList.begin(); }
+      iterator   end()   { return objectList.end(); }
+      value operator[] (S32 index) { return objectList[U32(index)]; }
+
+      iterator find( iterator first, iterator last, SimObject *obj)
+      { return ::find(first, last, obj); }
+
+      /// Reorder the position of "obj" to either be the last object in the list or, if
+      /// "target" is given, to come before "target" in the list of children.
+      virtual bool reOrder( SimObject *obj, SimObject *target=0 );
+      
+      /// Return the object at the given index.
+      SimObject* at(S32 index) const { return objectList.at(index); }
+
+      /// Remove all objects from this set.
+      virtual void clear();
+      
+      /// @}
+
+      /// @name Set Management
+      /// @{
+
+      /// Add the given object to the set.
+      /// @param object Object to add to the set.
+      virtual void addObject( SimObject* object );
+      
+      /// Remove the given object from the set.
+      /// @param object Object to remove from the set.
+      virtual void removeObject( SimObject* object );
+
+      /// Add the given object to the end of the object list of this set.
+      /// @param object Object to add to the set.
+      virtual void pushObject( SimObject* object );
+      
+      /// Return true if this set accepts the given object as a child.
+      /// This method should be overridden for set classes that restrict membership.
+      virtual bool acceptsAsChild( SimObject* object ) const { return true; }
+      
+      /// Deletes all the objects in the set.
+      void deleteAllObjects();
+
+      /// Remove an object from the end of the list.
+      virtual void popObject();
+
+      void bringObjectToFront(SimObject* obj) { reOrder(obj, front()); }
+      void pushObjectToBack(SimObject* obj) { reOrder(obj, NULL); }
+
+      /// Performs a sort of the objects in the set using a script
+      /// callback function to do the comparison.
+      ///
+      /// An example script sort callback:
+      ///
+      /// @code
+      ///   function sortByName( %object1, %object2 )
+      ///   {
+      ///      return strcmp( %object1.getName(), %object2.getName() );
+      ///   }
+      /// @endcode
+      ///
+      /// Note: You should never modify the SimSet itself while in
+      /// the sort callback function as it can cause a deadlock.
+      ///
+      void scriptSort( const String &scriptCallbackFn );
+      
+      /// @}
+
+      void callOnChildren( const String &method, S32 argc, const char *argv[], bool executeOnChildGroups = true );
+
+      /// Return the number of objects in this set as well as all sets that are contained
+      /// in this set and its children.
+      ///
+      /// @note The child sets themselves count towards the total too.
+      U32 sizeRecursive();
+
+      SimObject* findObjectByInternalName(StringTableEntry internalName, bool searchChildren = false);
+      SimObject* findObjectByLineNumber(const char* fileName, S32 declarationLine, bool searchChildren = false);   
+
+      /// Find the given object in this set.  Returns NULL if the object
+      /// is not part of this set.
+      SimObject* findObject( SimObject* object );
+
+      /// Add all child objects ( including children of children ) to the foundObjects
+      /// Vector which are of type T.
+
+      template< class T >
+      void findObjectByType( Vector<T*> &foundObjects );
+
+      /// Add all child objects ( including children of children ) to the foundObjects
+      /// Vector which are of type T and for which DecideAddObjectCallback return true;   
+
+      template< class T > 
+      void findObjectByCallback( bool ( *fn )( T* ), Vector<T*>& foundObjects );   
+      
+      SimObject* getRandom();
+
+      inline void lock()
+      {
+         #ifdef TORQUE_MULTITHREAD
+         Mutex::lockMutex(mMutex);
+         #endif
+      }
+
+      void unlock()
+      {
+         #ifdef TORQUE_MULTITHREAD
+         Mutex::unlockMutex(mMutex);
+         #endif
+      }
+
+      #ifdef TORQUE_DEBUG_GUARD
+      inline void _setVectorAssoc( const char *file, const U32 line )
+      {
+         objectList.setFileAssociation( file, line );
+      }
+      #endif
+
+      // SimObject.
+      DECLARE_CONOBJECT( SimSet );
+
+      virtual void onRemove();
+      virtual void onDeleteNotify(SimObject *object);
+
+      virtual SimObject* findObject( const char* name );
+
+      virtual void write(Stream &stream, U32 tabStop, U32 flags = 0);
+      virtual bool writeObject(Stream *stream);
+      virtual bool readObject(Stream *stream);
+
+      virtual SimSet* clone();
+};
+
+#ifdef TORQUE_DEBUG_GUARD
+#  define SIMSET_SET_ASSOCIATION( x ) x._setVectorAssoc( __FILE__, __LINE__ )
+#else
+#  define SIMSET_SET_ASSOCIATION( x )
+#endif
+
+template< class T >
+void SimSet::findObjectByType( Vector<T*> &foundObjects )
+{
+   T *curObj;
+   SimSet *curSet;
+
+   lock();
+
+   // Loop through our child objects.
+
+   SimObjectList::iterator itr = objectList.begin();   
+
+   for ( ; itr != objectList.end(); itr++ )
+   {
+      curObj = dynamic_cast<T*>( *itr );
+      curSet = dynamic_cast<SimSet*>( *itr );
+
+      // If child object is a set, call recursively into it.
+      if ( curSet )
+         curSet->findObjectByType( foundObjects ); 
+
+      // Add this child object if appropriate.
+      if ( curObj )
+         foundObjects.push_back( curObj );      
+   }
+
+   // Add this object if appropriate.
+   curObj = dynamic_cast<T*>(this);
+   if ( curObj )      
+      foundObjects.push_back( curObj );
+
+   unlock();
+}
+
+template< class T > 
+void SimSet::findObjectByCallback(  bool ( *fn )( T* ), Vector<T*> &foundObjects )
+{
+   T *curObj;
+   SimSet *curSet;
+
+   lock();
+
+   // Loop through our child objects.
+
+   SimObjectList::iterator itr = objectList.begin();   
+
+   for ( ; itr != objectList.end(); itr++ )
+   {
+      curObj = dynamic_cast<T*>( *itr );
+      curSet = dynamic_cast<SimSet*>( *itr );
+
+      // If child object is a set, call recursively into it.
+      if ( curSet )
+         curSet->findObjectByCallback( fn, foundObjects ); 
+
+      // Add this child object if appropriate.
+      if ( curObj && ( fn == NULL || fn( curObj ) ) )
+         foundObjects.push_back( curObj );      
+   }
+
+   // Add this object if appropriate.
+   curObj = dynamic_cast<T*>(this);
+   if ( curObj && ( fn == NULL || fn( curObj ) ) )      
+      foundObjects.push_back( curObj );
+
+   unlock();
+}
+
+/// An iterator that recursively and exhaustively traverses the contents
+/// of a SimSet.
+///
+/// @see SimSet
+class SimSetIterator
+{
+protected:
+   struct Entry {
+      SimSet* set;
+      SimSet::iterator itr;
+   };
+   class Stack: public Vector<Entry> {
+   public:
+      void push_back(SimSet*);
+   };
+   Stack stack;
+
+public:
+   SimSetIterator(SimSet*);
+   SimObject* operator++();
+   SimObject* operator*() {
+      return stack.empty()? 0: *stack.last().itr;
+   }
+};
+
+//---------------------------------------------------------------------------
+/// A group of SimObjects.
+///
+/// A SimGroup is a stricter form of SimSet. SimObjects may only be a member
+/// of a single SimGroup at a time.
+///
+/// The SimGroup will automatically enforce the single-group-membership rule.
+///
+/// @code
+///      // From engine/sim/simPath.cc - getting a pointer to a SimGroup
+///      SimGroup* pMissionGroup = dynamic_cast<SimGroup*>(Sim::findObject("MissionGroup"));
+///
+///      // From game/trigger.cc:46 - iterating over a SimObject's group.
+///      SimObject* trigger = ...;
+///      SimGroup* pGroup = trigger->getGroup();
+///      for (SimGroup::iterator itr = pGroup->begin(); itr != pGroup->end(); itr++)
+///      {
+///         // do something with *itr
+///      }
+/// @endcode
+class SimGroup: public SimSet
+{
+   public:
+   
+      typedef SimSet Parent;
+
+      friend class SimManager;
+      friend class SimObject;
+
+   private:
+
+      SimNameDictionary mNameDictionary;
+
+      void _addObject( SimObject* object, bool forcePushBack = false );
+      void _removeObjectNoLock( SimObject* );
+
+   public:
+
+      ~SimGroup();
+
+      void addObject( SimObject* object, SimObjectId id);
+      void addObject( SimObject* object, const char* name );
+
+      // SimSet.
+      virtual void addObject( SimObject* object );
+      virtual void removeObject( SimObject* object );
+      virtual void pushObject( SimObject* object );
+      virtual void popObject();
+      virtual void clear();
+      
+      virtual SimGroup* clone();
+      virtual SimGroup* deepClone();
+
+      virtual SimObject* findObject(const char* name);
+      virtual void onRemove();
+
+      virtual bool processArguments( S32 argc, const char** argv );
+
+      DECLARE_CONOBJECT( SimGroup );
+};
+
+inline void SimGroup::addObject(SimObject* obj, SimObjectId id)
+{
+   obj->mId = id;
+   dSprintf( obj->mIdString, sizeof( obj->mIdString ), "%u", obj->mId );
+   addObject( obj );
+}
+
+inline void SimGroup::addObject(SimObject *obj, const char *name)
+{
+   addObject( obj );
+   obj->assignName(name);
+}
+
+/// An iterator that recursively and exhaustively traverses all objects
+/// in an SimGroup object tree.
+class SimGroupIterator: public SimSetIterator
+{
+public:
+   SimGroupIterator(SimGroup* grp): SimSetIterator(grp) {}
+   SimObject* operator++();
+};
+
+#endif // _SIMSET_H_