src/Standard/Standard_MMgrOpt.hxx

   1 // Created on: 2005-03-15
   2 // Created by: Peter KURNEV
   3 // Copyright (c) 2005-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Standard_MMgrOpt_HeaderFile
  17 #define _Standard_MMgrOpt_HeaderFile
  18
  19 #include <Standard_MMgrRoot.hxx>
  20 #include <Standard_Mutex.hxx>
  21
  22 /**
  23 * @brief Open CASCADE memory manager optimized for speed.
  24 *
  25 * The behaviour is different for memory blocks of different sizes,
  26 * according to specified options provided to constructor:
  27 *
  28 * - Small blocks with size less than or equal to aCellSize are allocated
  29 *   in big pools of memory. The parameter aNbPages specifies size of
  30 *   these pools in pages (operating system-dependent).
  31 *   When freed, small block is not returned to the system but added
  32 *   into free blocks list and reused when block of the same size is
  33 *   requested.
  34 *
  35 * - Medium size blocks with size less than aThreshold are allocated
  36 *   using malloc() or calloc() function but not returned to the system
  37 *   when method Free() is called; instead they are put into free list
  38 *   and reused when block of the same size is requested.
  39 *   Blocks of medium size stored in free lists can be released to the
  40 *   system (by free()) by calling method Purge().
  41 *
  42 * - Large blocks with size greater than or equal to aThreshold are allocated
  43 *   and freed directly: either using malloc()/calloc() and free(), or using
  44 *   memory mapped files (if option aMMap is True)
  45 *
  46 * Thus the optimization of memory allocation/deallocation is reached
  47 * for small and medium size blocks using free lists method;
  48 * note that space allocated for small blocks cannot be (currently) released
  49 * to the system while space for medium size blocks can be released by method Purge().
  50 *
  51 * Note that destructor of that class frees all free lists and memory pools
  52 * allocated for small blocks.
  53 *
  54 * Note that size of memory blocks allocated by this memory manager is always
  55 * rounded up to 16 bytes. In addition, 8 bytes are added at the beginning
  56 * of the memory block to hold auxiliary information (size of the block when
  57 * in use, or pointer to the next free block when in free list).
  58 * This the expense of speed optimization. At the same time, allocating small
  59 * blocks is usually less costly than directly by malloc since allocation is made
  60 * once (when allocating a pool) and overheads induced by malloc are minimized.
  61 */
  62 class Standard_MMgrOpt : public Standard_MMgrRoot
  63 {
  64  public:
  65
  66   //! Constructor. If aClear is True, the allocated emmory will be
  67   //! nullified. For description of other parameters, see description
  68   //! of the class above.
  69   Standard_EXPORT Standard_MMgrOpt
  70                         (const Standard_Boolean aClear      = Standard_True,
  71                          const Standard_Boolean aMMap       = Standard_True,
  72                          const Standard_Size    aCellSize   = 200,
  73                          const Standard_Integer aNbPages    = 10000,
  74                          const Standard_Size    aThreshold  = 40000);
  75
  76   //! Frees all free lists and pools allocated for small blocks
  77   Standard_EXPORT virtual ~Standard_MMgrOpt();
  78
  79   //! Allocate aSize bytes; see class description above
  80   Standard_EXPORT virtual Standard_Address Allocate(const Standard_Size aSize);
  81
  82   //! Reallocate previously allocated aPtr to a new size; new address is returned.
  83   //! In case that aPtr is null, the function behaves exactly as Allocate.
  84   Standard_EXPORT virtual Standard_Address Reallocate (Standard_Address thePtr,
  85                                                        const Standard_Size theSize);
  86
  87   //! Free previously allocated block.
  88   //! Note that block can not all blocks are released to the OS by this
  89   //! method (see class description)
  90   Standard_EXPORT virtual void Free (Standard_Address thePtr);
  91
  92   //! Release medium-sized blocks of memory in free lists to the system.
  93   //! Returns number of actually freed blocks
  94   Standard_EXPORT virtual Standard_Integer Purge(Standard_Boolean isDestroyed);
  95
  96   //! Declaration of a type pointer to the callback function that should accept the following arguments:
  97   //! @param theIsAlloc   true if the data is allocated, false if it is freed
  98   //! @param theStorage   address of the allocated/freed block
  99   //! @param theRoundSize the real rounded size of the block
 100   //! @param theSize      the size of the block that was requested by application (this value is correct only if theIsAlloc is true)
 101   typedef void (*TPCallBackFunc)(const Standard_Boolean theIsAlloc,
 102                                  const Standard_Address theStorage,
 103                                  const Standard_Size theRoundSize,
 104                                  const Standard_Size theSize);
 105
 106   //! Set the callback function. You may pass 0 there to turn off the callback.
 107   //! The callback function, if set, will be automatically called from within
 108   //! Allocate and Free methods.
 109   Standard_EXPORT static void SetCallBackFunction(TPCallBackFunc pFunc);
 110
 111 protected:
 112
 113   //! Internal - initialization of buffers
 114   Standard_EXPORT void Initialize();
 115
 116   //! Internal - allocation of memory using either malloc or memory mapped files.
 117   //! The size of the actually allocated block may be greater than requested one
 118   //! when memory mapping is used, since it is aligned to page size
 119   Standard_Size* AllocMemory (Standard_Size &aSize);
 120
 121   //! Internal - deallocation of memory taken by AllocMemory
 122   void FreeMemory (Standard_Address aPtr, const Standard_Size aSize);
 123
 124   //! Internal - free memory pools allocated for small size blocks
 125   void FreePools();
 126
 127  protected:
 128   Standard_Boolean myClear;         //!< option to clear allocated memory
 129
 130   Standard_Size    myFreeListMax;   //!< last allocated index in the free blocks list
 131   Standard_Size ** myFreeList;      //!< free blocks list
 132
 133   Standard_Size    myCellSize;      //!< small blocks size
 134   Standard_Integer myNbPages;       //!< size (pages) for small block memory pools
 135   Standard_Size    myPageSize;      //!< system-dependent memory page size
 136   Standard_Size *  myAllocList;     //!< list of memory pools for small blocks
 137   Standard_Size *  myNextAddr;      //!< next free address in the active memory pool
 138   Standard_Size *  myEndBlock;      //!< end of the active memory pool
 139
 140   Standard_Integer myMMap;          //!< non-null if using memory mapped files for allocation of large blocks
 141   Standard_Size    myThreshold;     //!< large block size
 142
 143   Standard_Mutex   myMutex;         //!< Mutex to protect free lists data
 144   Standard_Mutex   myMutexPools;    //!< Mutex to protect small block pools data
 145 };
 146
 147 #endif