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

   1 # Introduction
   2
   3 zend-memory assists with managing data in an environment with limited memory.
   4
   5 Memory objects (memory containers) are generated by the memory manager at your
   6 request and transparently swapped/loaded when necessary.
   7
   8 For example, if creating or loading a managed object would cause the total
   9 memory usage to exceed the limit you specify, some managed objects are copied to
  10 cache storage outside of memory. In this way, the total memory used by managed
  11 objects does not exceed the limit you need to enforce. To provide this
  12 functionality, the memory manager can compose [zend-cache storage adapters](http://zendframework.github.io/zend-cache/storage/adapter/)
  13 as storage providers.
  14
  15 ## Usage
  16
  17 Instantiate the memory manager class:
  18
  19 ```php
  20 use Zend\Memory\MemoryManager;
  21
  22 // No caching backend:
  23 $memoryManager = new MemoryManager();
  24 ```
  25
  26 Optionally, you can create a cache storage adapter, and pass it to the
  27 `MemoryManager` constructor:
  28
  29 ```php
  30 use Zend\Cache\StorageFactory;
  31 use Zend\Memory\MemoryManager;
  32
  33 // Use a filesystem adapter, placing memory blocks in the tmp directory
  34 // under which the application is running.
  35 $cache = StorageFactory::factory([
  36     'adapter' => [
  37         'name' => 'filesystem',
  38         'options' => ['cache_dir' => './tmp/'],
  39     ],
  40 ]);
  41
  42 $memoryManager = new MemoryManager($cache);
  43 ```
  44
  45 Once you have a `MemoryManager` instance, you can start pushing values to it and
  46 pulling values from it.
  47
  48 ```php
  49 $loadedFiles = array();
  50
  51 for ($count = 0; $count < 10000; $count++) {
  52     $f = fopen($fileNames[$count], 'rb');
  53     $data = fread($f, filesize($fileNames[$count]));
  54     $fclose($f);
  55
  56     $loadedFiles[] = $memoryManager->create($data);
  57 }
  58
  59 echo $loadedFiles[$index1]->value;
  60
  61 $loadedFiles[$index2]->value = $newValue;
  62
  63 $loadedFiles[$index3]->value[$charIndex] = '_';
  64 ```
  65
  66 ## Theory of Operation
  67
  68 zend-memory operates with the following concepts:
  69
  70 - Memory manager
  71 - Memory container
  72   - Locked memory object
  73   - Movable memory object
  74
  75 ### Memory manager
  76
  77 The memory manager generates memory objects (locked or movable) by request of
  78 the application, and returns them wrapped into a memory container object.
  79
  80 ### Memory container
  81
  82 The memory container has a virtual or actual `value` attribute of type `string`.
  83 This attribute contains the data value specified at memory object creation time.
  84
  85 You can operate with this `value` attribute as an object property:
  86
  87 ```php
  88 $memObject = $memoryManager->create($data);
  89
  90 echo $memObject->value;
  91
  92 $memObject->value = $newValue;
  93
  94 $memObject->value[$index] = '_';
  95
  96 echo ord($memObject->value[$index1]);
  97
  98 $memObject->value = substr($memObject->value, $start, $length);
  99 ```
 100
 101 ### Locked memory
 102
 103 Locked memory objects are always stored in memory. Data stored in locked memory
 104 are never swapped to the cache backend.
 105
 106 ### Movable memory
 107
 108 Movable memory objects are transparently swapped and loaded to/from the cache
 109 backend by the `MemoryManager` when necessary.
 110
 111 The memory manager does not swap objects with size less than the specified
 112 minimum, due to performance considerations. See [the settings section](memory-manager.md#settings)
 113 for more details.