include/IReferenceCounted.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_IREFERENCE_COUNTED_H_INCLUDED__\r
   6 #define __I_IREFERENCE_COUNTED_H_INCLUDED__\r
   7 \r
   8 #include "irrTypes.h"\r
   9 \r
  10 namespace irr\r
  11 {\r
  12 \r
  13         //! Base class of most objects of the Irrlicht Engine.\r
  14         /** This class provides reference counting through the methods grab() and drop().\r
  15         It also is able to store a debug string for every instance of an object.\r
  16         Most objects of the Irrlicht\r
  17         Engine are derived from IReferenceCounted, and so they are reference counted.\r
  18 \r
  19         When you create an object in the Irrlicht engine, calling a method\r
  20         which starts with 'create', an object is created, and you get a pointer\r
  21         to the new object. If you no longer need the object, you have\r
  22         to call drop(). This will destroy the object, if grab() was not called\r
  23         in another part of you program, because this part still needs the object.\r
  24         Note, that you only need to call drop() to the object, if you created it,\r
  25         and the method had a 'create' in it.\r
  26 \r
  27         A simple example:\r
  28 \r
  29         If you want to create a texture, you may want to call an imaginable method\r
  30         IDriver::createTexture. You call\r
  31         ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128));\r
  32         If you no longer need the texture, call texture->drop().\r
  33 \r
  34         If you want to load a texture, you may want to call imaginable method\r
  35         IDriver::loadTexture. You do this like\r
  36         ITexture* texture = driver->loadTexture("example.jpg");\r
  37         You will not have to drop the pointer to the loaded texture, because\r
  38         the name of the method does not start with 'create'. The texture\r
  39         is stored somewhere by the driver.\r
  40         */\r
  41         class IReferenceCounted\r
  42         {\r
  43         public:\r
  44 \r
  45                 //! Constructor.\r
  46                 IReferenceCounted()\r
  47                         : DebugName(0), ReferenceCounter(1)\r
  48                 {\r
  49                 }\r
  50 \r
  51                 //! Destructor.\r
  52                 virtual ~IReferenceCounted()\r
  53                 {\r
  54                 }\r
  55 \r
  56                 //! Grabs the object. Increments the reference counter by one.\r
  57                 /** Someone who calls grab() to an object, should later also\r
  58                 call drop() to it. If an object never gets as much drop() as\r
  59                 grab() calls, it will never be destroyed. The\r
  60                 IReferenceCounted class provides a basic reference counting\r
  61                 mechanism with its methods grab() and drop(). Most objects of\r
  62                 the Irrlicht Engine are derived from IReferenceCounted, and so\r
  63                 they are reference counted.\r
  64 \r
  65                 When you create an object in the Irrlicht engine, calling a\r
  66                 method which starts with 'create', an object is created, and\r
  67                 you get a pointer to the new object. If you no longer need the\r
  68                 object, you have to call drop(). This will destroy the object,\r
  69                 if grab() was not called in another part of you program,\r
  70                 because this part still needs the object. Note, that you only\r
  71                 need to call drop() to the object, if you created it, and the\r
  72                 method had a 'create' in it.\r
  73 \r
  74                 A simple example:\r
  75 \r
  76                 If you want to create a texture, you may want to call an\r
  77                 imaginable method IDriver::createTexture. You call\r
  78                 ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128));\r
  79                 If you no longer need the texture, call texture->drop().\r
  80                 If you want to load a texture, you may want to call imaginable\r
  81                 method IDriver::loadTexture. You do this like\r
  82                 ITexture* texture = driver->loadTexture("example.jpg");\r
  83                 You will not have to drop the pointer to the loaded texture,\r
  84                 because the name of the method does not start with 'create'.\r
  85                 The texture is stored somewhere by the driver. */\r
  86                 void grab() const { ++ReferenceCounter; }\r
  87 \r
  88                 //! Drops the object. Decrements the reference counter by one.\r
  89                 /** The IReferenceCounted class provides a basic reference\r
  90                 counting mechanism with its methods grab() and drop(). Most\r
  91                 objects of the Irrlicht Engine are derived from\r
  92                 IReferenceCounted, and so they are reference counted.\r
  93 \r
  94                 When you create an object in the Irrlicht engine, calling a\r
  95                 method which starts with 'create', an object is created, and\r
  96                 you get a pointer to the new object. If you no longer need the\r
  97                 object, you have to call drop(). This will destroy the object,\r
  98                 if grab() was not called in another part of you program,\r
  99                 because this part still needs the object. Note, that you only\r
 100                 need to call drop() to the object, if you created it, and the\r
 101                 method had a 'create' in it.\r
 102 \r
 103                 A simple example:\r
 104 \r
 105                 If you want to create a texture, you may want to call an\r
 106                 imaginable method IDriver::createTexture. You call\r
 107                 ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128));\r
 108                 If you no longer need the texture, call texture->drop().\r
 109                 If you want to load a texture, you may want to call imaginable\r
 110                 method IDriver::loadTexture. You do this like\r
 111                 ITexture* texture = driver->loadTexture("example.jpg");\r
 112                 You will not have to drop the pointer to the loaded texture,\r
 113                 because the name of the method does not start with 'create'.\r
 114                 The texture is stored somewhere by the driver.\r
 115                 \return True, if the object was deleted. */\r
 116                 bool drop() const\r
 117                 {\r
 118                         // someone is doing bad reference counting.\r
 119                         _IRR_DEBUG_BREAK_IF(ReferenceCounter <= 0)\r
 120 \r
 121                         --ReferenceCounter;\r
 122                         if (!ReferenceCounter)\r
 123                         {\r
 124                                 delete this;\r
 125                                 return true;\r
 126                         }\r
 127 \r
 128                         return false;\r
 129                 }\r
 130 \r
 131                 //! Get the reference count.\r
 132                 /** \return Current value of the reference counter. */\r
 133                 s32 getReferenceCount() const\r
 134                 {\r
 135                         return ReferenceCounter;\r
 136                 }\r
 137 \r
 138                 //! Returns the debug name of the object.\r
 139                 /** The Debugname may only be set and changed by the object\r
 140                 itself. This method should only be used in Debug mode.\r
 141                 \return Returns a string, previously set by setDebugName(); */\r
 142                 const c8* getDebugName() const\r
 143                 {\r
 144                         return DebugName;\r
 145                 }\r
 146 \r
 147         protected:\r
 148 \r
 149                 //! Sets the debug name of the object.\r
 150                 /** The Debugname may only be set and changed by the object\r
 151                 itself. This method should only be used in Debug mode.\r
 152                 \param newName: New debug name to set. */\r
 153                 void setDebugName(const c8* newName)\r
 154                 {\r
 155                         DebugName = newName;\r
 156                 }\r
 157 \r
 158         private:\r
 159 \r
 160                 //! The debug name.\r
 161                 const c8* DebugName;\r
 162 \r
 163                 //! The reference counter. Mutable to do reference counting on const objects.\r
 164                 mutable s32 ReferenceCounter;\r
 165         };\r
 166 \r
 167 } // end namespace irr\r
 168 \r
 169 #endif\r
 170 \r