vendor/zendframework/zend-memory/doc/book/memory-manager.md

   1 # Memory Manager
   2
   3 ## Creating a Memory Manager
   4
   5 You can create new a memory manager (`Zend\Memory\MemoryManager` object) using its constructor:
   6
   7 ```php
   8 __construct(Zend\Cache\Storage\StorageInterface $cache = null) : void
   9 ```
  10
  11 As an example, the following creates an instance which *is not* backed by cache
  12 storage:
  13
  14 ```php
  15 $memoryManager = new Zend\Memory\MemoryManager();
  16 ```
  17
  18 While the following creates an instance backed by a filesystem cache storage
  19 adapter, storing memory blocks in the `tmp/` directory of the current working
  20 directory:
  21
  22 ```php
  23 use Zend\Cache\StorageFactory;
  24 use Zend\Memory\MemoryManager;
  25
  26 $cache = StorageFactory::factory([
  27     'adapter' => [
  28         'name' => 'Filesystem',
  29         'options' => [
  30             'cache_dir' => './tmp/', // Directory in which to put swapped memory blocks
  31         ],
  32     ],
  33 ]);
  34
  35 $memoryManager = new MemoryManager($cache);
  36 ```
  37
  38 The `MemoryManager` uses [zend-cache storage adapters](http://zendframework.github.io/zend-cache/storage/adapter/)
  39 to cache memory blocks; if no cache instance is provided, the system temporary
  40 directory is used. This is useful if you know that memory is not limited or the
  41 overall size of objects never reaches the memory limit.
  42
  43 ## Managing Memory Objects
  44
  45 This section describes creating and destroying objects in the managed memory,
  46 and settings to control memory manager behavior.
  47
  48 ### Creating Movable Objects
  49
  50 Create movable objects (objects which may be swapped into cache storage) using
  51 the `Zend\Memory\MemoryManager::create([$data])` method:
  52
  53 ```php
  54 $memObject = $memoryManager->create($data);
  55 ```
  56
  57 The `$data` argument is optional and used to initialize the object value. If the
  58 `$data` argument is omitted, the value is an empty string.
  59
  60 ### Creating Locked Objects
  61
  62 Create locked objects (objects which will never be swapped into cache storage)
  63 using the `Zend\Memory\MemoryManager::createLocked([$data])` method:
  64
  65 ```php
  66 $memObject = $memoryManager->createLocked($data);
  67 ```
  68
  69 The `$data` argument is optional and used to initialize the object value. If the
  70 `$data` argument is omitted, the value is an empty string.
  71
  72 ### Destroying Objects
  73
  74 Memory objects are automatically destroyed and removed from memory when they go
  75 out of scope:
  76
  77 ```php
  78 function foo() use ($memoryManager, $memList) {
  79     // ...
  80
  81     $memObject1 = $memoryManager->create($data1);
  82     $memObject2 = $memoryManager->create($data2);
  83     $memObject3 = $memoryManager->create($data3);
  84
  85     // ...
  86
  87     $memList[] = $memObject3;
  88
  89     // ...
  90
  91     unset($memObject2); // $memObject2 is destroyed here
  92
  93     // ...
  94     // $memObject1 is destroyed here
  95     // but $memObject3 object is still referenced by $memList
  96     // and is not destroyed
  97 }
  98 ```
  99
 100 This applies to both movable and locked objects.
 101
 102 ## Settings
 103
 104 ### Memory Limit
 105
 106 The memory limit is the maximum number of bytes allowed for use by loaded
 107 movable objects.
 108
 109 If loading or creation of an object causes memory usage to exceed of this limit,
 110 then the memory manager swaps some other objects.
 111
 112 You can retrieve or set the memory limit setting using the `getMemoryLimit()` and
 113 `setMemoryLimit($newLimit)` methods:
 114
 115 ```php
 116 $oldLimit = $memoryManager->getMemoryLimit();  // Get memory limit in bytes
 117 $memoryManager->setMemoryLimit($newLimit);     // Set memory limit in bytes
 118 ```
 119
 120 A negative value for memory limit means 'no limit'.
 121
 122 The default value is two-thirds of the value of `memory_limit` in `php.ini` or
 123 'no limit' (-1) if `memory_limit` is not set in `php.ini`.
 124
 125 ### MinSize
 126
 127 The `MinSize` is the minimum size an object must be before it will be swapped to a
 128 cache backend; objects with sizes smaller than this value will not be swapped.
 129 This reduces the number of swap/load operations.
 130
 131 You can retrieve or set the minimum size using the `getMinSize()` and
 132 `setMinSize($newSize)` methods:
 133
 134 ```php
 135 $oldMinSize = $memoryManager->getMinSize();  // Get MinSize in bytes
 136 $memoryManager->setMinSize($newSize);        // Set MinSize limit in bytes
 137 ```
 138
 139 The default minimum size value is 16KB (16384 bytes).