BVB Source Codes

CRYENGINE Show Reference.h Source code

Return Download CRYENGINE: download Reference.h Source code - Download CRYENGINE Source code - Type:.h
  1. // Copyright 2001-2016 Crytek GmbH / Crytek Group. All rights reserved.
  2.  
  3. // -------------------------------------------------------------------------
  4. //  File name:   Reference.h
  5. //  Created:     11/02/2008 by Matthew
  6. //  Description: References to AI objects
  7. // -------------------------------------------------------------------------
  8. //  History:
  9. //
  10. //  Notes:
  11. //    - this-> is used when referring to members to compile on GCC - due to specialization rules compiler
  12. //      cannot assume any inherited members exist in a templated base (Meyer, Item 43, Effective C++)
  13. ////////////////////////////////////////////////////////////////////////////
  14.  
  15. /**
  16.  * References to AI objects.
  17.  *
  18.  * (More accurately: smartpointers)
  19.  * These references can be preserved across frames and dereferenced to give an AIStub * or AIObject *, which should
  20.  * always be discarded between frames.
  21.  * There are four main types:
  22.  * tAIObjectID -  A simple integer ID. This is the only type that should pass outside the AI system.
  23.  * WeakRef -      Wraps an ID with templated type. For use within the AI system.
  24.  * StrongRef -    Wraps an ID with templated type and auto_ptr semantics. Uniquely owns the object, controlling its validity. Within AI.
  25.  * CountedRef -   Wraps a StrongRef for reference-counting semantics. Within AI.
  26.  *
  27.  * Notes:
  28.  * Strong should be preferred but are not compatible (and will not compile) with STL containers. Counted can be used in this case.
  29.  * Counted is rather bolted on and should be properly integrated!
  30.  */
  31.  
  32. #ifndef __AI_REFERENCE_H_
  33. #define __AI_REFERENCE_H_
  34.  
  35. #pragma once
  36.  
  37. //#define DEBUG_REFERENCES
  38.  
  39. /**
  40.  * The simple integer AI object ID, for use outside the AI system.
  41.  */
  42.  
  43. // (MATT) This should really live in a minimal AI include, which right now we don't have  {2009/04/08}
  44. #ifndef INVALID_AIOBJECTID
  45. typedef uint32 tAIObjectID;
  46.         #define INVALID_AIOBJECTID ((tAIObjectID)(0))
  47. #endif
  48.  
  49. template<class T> class CWeakRef;
  50. template<class T> class CStrongRef;
  51. template<class T> class CCountedRef;
  52. class CAIObject;
  53.  
  54. /**
  55.  * Enum whose single member, NILREF, represents an empty, untyped reference.
  56.  * Only for syntactic sugar, to avoid the use of CWeakRef<CMyClass>() where, with pointers, NULL would have sufficed.
  57.  * It is silently converted into a Nil weak reference of any type, hence very useful as a parameter when calling a function.
  58.  */
  59. enum type_nil_ref { NILREF };
  60.  
  61. /**
  62.  * An abstract typeless base class for references.
  63.  * Some functionality of the references is independent of type and so is defined here.
  64.  */
  65. class CAbstractUntypedRef
  66. {
  67.         friend class CObjectContainer;
  68.  
  69. public:
  70.         /**
  71.          * Test if reference is currently unassigned.
  72.          * Being assigned does not imply validity. Test for this with IsValid().
  73.          * @return True if currently assigned to an object.
  74.          */
  75.         ILINE bool IsNil() const;
  76.  
  77.         /**
  78.          * Test if reference is currently assigned.
  79.          * Being assigned does not imply validity. Test for this with IsValid().
  80.          * This method is simply the converse of IsNil - but avoids potential double-negation confusion in its usage.
  81.          * @return True if currently assigned to an object.
  82.          */
  83.         ILINE bool IsSet() const;
  84.  
  85.         /**
  86.          * Return a simple AI object ID.
  87.          * @return the tAIObjectID wrapped, regardless of validity. INVALID_AIOBJECTID if unassigned;
  88.          */
  89.         ILINE tAIObjectID GetObjectID() const;
  90.  
  91.         /**
  92.          * Return the AI object, if reference is valid.
  93.          * The object may have been removed since the reference was assigned.
  94.          * @return Pointer to a valid AI object or NULL.
  95.          */
  96.         ILINE IAIObject* GetIAIObject() const;
  97.  
  98.         /**
  99.          * Tests whether a reference and a pointer refer to the same object.
  100.          * An invalid reference and a NULL pointer compare false for now, but that is debatable.
  101.          * @return true iff reference is Valid and refers to the same object as the pointer, or Nil and pointer is NULL
  102.          */
  103.         ILINE bool operator==(const IAIObject* const pThatObject) const;
  104.  
  105.         /**
  106.          * Negation of operator== for a pointer
  107.          */
  108.         ILINE bool operator!=(const IAIObject* const pThatObject) const;
  109.  
  110.         /**
  111.          * Tests whether two references refer to the same object.
  112.          * For now, if either reference is invalid we return false, even if both are invalid or even both refer to the same invalid object, which is debatable
  113.          * @return true iff references are to the same Valid object or are both Nil
  114.          */
  115.         ILINE bool operator==(const CAbstractUntypedRef& that) const;
  116.  
  117.         /**
  118.          * Negation of operator== for another reference
  119.          */
  120.         ILINE bool operator!=(const CAbstractUntypedRef& that) const;
  121.  
  122.         /**
  123.          * Comparison operator to allow use in sorted containers
  124.          */
  125.         ILINE bool operator<(const CAbstractUntypedRef& that) const;
  126.  
  127. protected:
  128.         // Allow just CObjectContainer to create these, and we trust it to have ensured the type is appropriate
  129.         ILINE void Assign(tAIObjectID nID);
  130.  
  131.         tAIObjectID m_nID;
  132. };
  133.  
  134. /**
  135.  * An abstract typed base class for references.
  136.  * Some functionality of the references is independent of type and so is defined here.
  137.  */
  138. template<class T> class CAbstractRef : public CAbstractUntypedRef
  139. {
  140. public:
  141.  
  142.         /**
  143.          * Get a typed weak reference instance from any existing reference.
  144.          * Weak references can be created from both strong and weak references.
  145.          * @return A weak reference to the same object, if any.
  146.          */
  147.         ILINE CWeakRef<T> GetWeakRef() const;
  148. };
  149.  
  150. /**
  151.  * Typed strong reference for defining ownership, with auto_ptr semantics.
  152.  * An AI object can only be owned by just one strong reference.
  153.  * They are by definition always valid until Released.
  154.  * Strong references can only be assigned centrally by the system when the object is created and only passes around by single-transferrable ownership.
  155.  * If you need more - for instance STL-container compatability - see CCountedRef below.
  156.  */
  157. template<class T = CAIObject> class CStrongRef : public CAbstractRef<T>
  158. {
  159. public:
  160.         /**
  161.          * Construct an unassigned (nil) reference.
  162.          */
  163.         ILINE CStrongRef();
  164.  
  165.         /**
  166.          * Single transferable ownership constructor.
  167.          */
  168.         ILINE CStrongRef(CStrongRef& ref);
  169.  
  170.         /**
  171.          * Convert a NilRef into an unassigned strong reference.
  172.          * Technically this is a copy-constructor but it's really just syntactic sugar
  173.          */
  174.         ILINE CStrongRef(type_nil_ref);
  175.  
  176.         /**
  177.          * Destructor automatically releases any object owned.
  178.          */
  179.         ILINE ~CStrongRef();
  180.  
  181.         /**
  182.          * Single transferable ownership assignment.
  183.          */
  184.         ILINE CStrongRef<T>& operator=(CStrongRef& ref);
  185.  
  186.         // Don't perform any stub checking as this is strong
  187.         T* GetAIObject() const;
  188.  
  189.         // Don't perform any stub checking as this is strong
  190.         ILINE IAIObject* GetIAIObject() const;
  191.  
  192.         /**
  193.          * Release any object owned.
  194.          * Deliberately named differently to the Reset method in weak references, because Releasing
  195.          * a strong reference causes object deregistration - which is a much more significant event.
  196.          * @return true iff this reference owned an object
  197.          */
  198.         ILINE bool Release();
  199.  
  200.         ILINE      operator bool() const;
  201.  
  202.         void       Serialize(TSerialize ser, const char* sName = NULL);
  203.  
  204.         // Could define deref here - semantics are same as pointer for strong
  205.         // Conversely, removing this is helpful in finding dodgy places in the code!
  206.         ILINE T* operator->() const;
  207.  
  208. protected:
  209.         // In principle, we could cache the CAIObject pointer here - but whether it's worth the bloat is debatable, especially with non-trivial stub
  210.  
  211.         ILINE tAIObjectID GiveOwnership();
  212. };
  213.  
  214. /**
  215.  * Template function to convert a typed weak reference to another type.
  216.  * Typed references can be cast implicitly to another type if the bare pointer could be cast implicitly.
  217.  * Where that is not the case, StaticCast can explicitly cast to another type, if static_cast would accomplish this for a bare pointer.
  218.  * This method, like static_cast, does not perform dynamic type checking.
  219.  */
  220. template<class S, class U>
  221. ILINE CWeakRef<S> StaticCast(const CAbstractRef<U>& ref);
  222.  
  223. /**
  224.  * Typed weak reference.
  225.  * Weak references allow AI code to refer to an AI object that it does not own.
  226.  * A weak reference may be invalidated by the object being Released at _any_ time.
  227.  * However, any pointer obtained from is guaranteed valid until the end of the frame.
  228.  * Weak references are easily obtained from other strong or weak references.
  229.  * They may be passed around and stored freely.
  230.  */
  231. template<class T = CAIObject> class CWeakRef : public CAbstractRef<T>
  232. {
  233.         friend class CObjectContainer;
  234.         friend class CAbstractRef<T>;
  235.         friend class CCountedRef<T>;
  236.  
  237.         template<class S, class U>
  238.         friend CWeakRef<S> StaticCast(const CAbstractRef<U>& ref);
  239.  
  240. public:
  241.         /**
  242.          * Construct an unassigned weak reference.
  243.          */
  244.         ILINE CWeakRef();
  245.  
  246.         /**
  247.          * Construct a weak reference from any typed reference.
  248.          */
  249.         template<class S>
  250.         ILINE CWeakRef(const CAbstractRef<S>& ref);
  251.  
  252.         /**
  253.          * Convert a NilRef into an unassigned weak reference.
  254.          * Technically this is a copy-constructor but it's really just syntactic sugar
  255.          */
  256.         ILINE CWeakRef(type_nil_ref);
  257.  
  258.         /**
  259.          * Deassign this weak reference.
  260.          * This will not affect the object itself or any other references to it.
  261.          */
  262.         ILINE void Reset();
  263.  
  264.         /**
  265.          * Deassign this weak reference.
  266.          * This will not affect the object itself or any other references to it.
  267.          */
  268.         ILINE bool IsReset() const;
  269.  
  270.         /**
  271.          * If this reference is invalid, reset it to Nil.
  272.          * Returns whether it was valid or not.
  273.          * Often useful to resolve an argument, ensuring it is Valid or Nil before storing it.
  274.          */
  275.         ILINE bool ValidateOrReset();
  276.  
  277.         /**
  278.          * Acts like GetAIObject(), but if invalid Reset to Nil.
  279.          * Often useful to check update status of stored references while checking their validity.
  280.          */
  281.         ILINE T*   GetAIObjectOrReset();
  282.  
  283.         ILINE T*   GetAIObject() const;
  284.  
  285.         ILINE bool IsValid() const;
  286.  
  287.         /**
  288.          * Assign a weak weak reference from any typed reference.
  289.          */
  290.         ILINE void Assign(const CAbstractRef<T>& ref);
  291.  
  292.         void       Serialize(TSerialize ser, const char* sName = NULL);
  293.  
  294. protected:
  295.         // Allow just CObjectManager to create in this way and we trust it to have ensured the type is appropriate
  296.         // This can probably go away eventually
  297.         // Note that when converting over from pointers, use of 0 as an argument can cause complaints of protected member here
  298.         ILINE CWeakRef(tAIObjectID nID);
  299. };
  300.  
  301. /**
  302.  * Get a weak reference to the given object, of the same type as the object pointer.
  303.  * Convenience method, currently with incredibly slow implementation.
  304.  */
  305. template<class T>
  306. CWeakRef<T> GetWeakRef(T* pObject);
  307.  
  308. template<class T>
  309. void SerialisationHack(TSerialize ser, const char* sName, T** pObj);
  310.  
  311. /**
  312.  * Typed counted reference for defining ownership in objects while being STL-compatible.
  313.  * Can only be initialised from strong references or other counted references.
  314.  * They are by definition always valid until Released.
  315.  * Strong references can only be assigned centrally by the system when the object is created and cannot be passed around.
  316.  */
  317.  
  318. // Implementation notes:
  319. // Example reference counting classes often must be assigned and assume a valid counter object. Here we can be unassigned, like Strong.
  320. // This _isn't_ an abstract ref! It shouldn't directly contain an ID. A bit of restructuring might be required here.
  321. template<class T = CAIObject> class CCountedRef
  322. {
  323. public:
  324.  
  325. #ifdef DEBUG_REFERENCES
  326.         CAIObject * pObj;
  327. #endif
  328.  
  329.         /**
  330.          * Construct an unassigned (nil) reference.
  331.          */
  332.         ILINE CCountedRef();
  333.  
  334.         /**
  335.          * Construction from a strong ref (which is loses its single-transferable ownership)
  336.          */
  337.         ILINE CCountedRef(CStrongRef<T>& ref);
  338.  
  339.         /**
  340.          * Copy constructor.
  341.          */
  342.         ILINE CCountedRef(const CCountedRef& ref);
  343.  
  344.         /**
  345.          * Convert a NilRef into an unassigned counted reference.
  346.          * Technically this is a copy-constructor but it's really just syntactic sugar
  347.          */
  348.         ILINE CCountedRef(type_nil_ref);
  349.  
  350.         /**
  351.          * Counted reference assignment.
  352.          */
  353.         ILINE CCountedRef& operator=(const CCountedRef& ref);
  354.  
  355.         /**
  356.          * Destructor, of course, decrements the reference count and possibly deregisters the object.
  357.          */
  358.         ILINE ~CCountedRef();
  359.  
  360.         ILINE bool IsNil() const;
  361.  
  362.         /**
  363.          * Decrement the count on any object owned, possibly causing the object to be deregistered.
  364.          * Same name convention as Strong ref as it can have the same consequences.
  365.          * @return true iff this reference was counting an object.
  366.          */
  367.         ILINE bool Release();
  368.  
  369.         ILINE      operator bool() const;
  370.  
  371.         void       Serialize(TSerialize ser, const char* sName = NULL);
  372.  
  373.         ILINE bool operator==(const IAIObject* const pThatObject) const;
  374.         ILINE bool operator==(const CAbstractUntypedRef& that) const;
  375.  
  376.         /**
  377.          * Get a typed weak reference instance from any existing reference.
  378.          * Weak references can be created from both strong and weak references.
  379.          * @return A weak reference to the same object, if any.
  380.          */
  381.         ILINE CWeakRef<T> GetWeakRef() const;
  382.  
  383.         ILINE T*          GetAIObject() const;
  384.  
  385.         // Could define deref here - semantics are same as pointer for strong
  386.         // Conversely, removing this is helpful in finding dodgy places in the code!
  387.         ILINE T* operator->() const;
  388.  
  389.         /**
  390.          * Return a simple AI object ID.
  391.          * @return the tAIObjectID wrapped, regardless of validity. INVALID_AIOBJECTID if unassigned;
  392.          */
  393.         ILINE tAIObjectID GetObjectID() const;
  394.  
  395. protected:
  396.         // In principle, we could cache the m_nID or CAIObject pointer here - but whether it's worth the bloat is debatable, especially with non-trivial stub
  397.  
  398.         struct SRefCounter
  399.         {
  400.                 SRefCounter()
  401.                         : m_nRefs(1)
  402.                 {
  403.                 } // Start at 1
  404.                 ~SRefCounter()
  405.                 {
  406.                 }
  407.  
  408.                 // Strong ref released automatically
  409.                 CStrongRef<T> m_strongRef;
  410.                 int           m_nRefs;        // Since this isn't in the object itself, it needn't be mutable
  411.         };
  412.  
  413.         SRefCounter* m_pCounter;
  414.  
  415.         // For now, we just use new and delete, but a pool seems sensible
  416.         ILINE void ObtainCounter();
  417.         ILINE void ReleaseCounter();
  418.  
  419.         // (MATT) Force a release to a strong ref. Only makes sense when count is 1 - or we will leave dangling pointers to a deleted counter {2009/03/30}
  420.         ILINE void ForceReleaseCounter();
  421. };
  422.  
  423. #endif // __AI_REFERENCE_H_
  424.  
downloadReference.h Source code - Download CRYENGINE Source code
Related Source Codes/Software:
postal - 2017-06-11
reactide - Reactide is the first dedicated IDE for React web ... 2017-06-11
rkt - rkt is a pod-native container engine for Linux. It... 2017-06-11
uWebSockets - Tiny WebSockets https://for... 2017-06-11
realworld - TodoMVC for the RealWorld - Exemplary fullstack Me... 2017-06-11
CRYENGINE - CRYENGINE is a powerful real-time game development... 2017-06-11
goreplay - GoReplay is an open-source tool for capturing and ... 2017-06-10
pyenv - Simple Python version management 2017-06-10
redux-saga - An alternative side effect model for Redux apps ... 2017-06-10
angular-starter - 2017-06-10

 Back to top