documentation/manual/en/module_specs/Zend_Memory-MemoryManager.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.memory.memory-manager">
   4     <title>Memory Manager</title>
   5
   6     <sect2 id="zend.memory.memory-manager.creation">
   7         <title>Creating a Memory Manager</title>
   8
   9         <para>
  10             You can create new a memory manager
  11             (<classname>Zend_Memory_Manager</classname> object) using the
  12             <methodname>Zend_Memory::factory($backendName [, $backendOprions])</methodname>
  13             method.
  14         </para>
  15
  16         <para>
  17             The first argument <varname>$backendName</varname> is a string that
  18             names one of the backend implementations supported by <classname>Zend_Cache</classname>.
  19         </para>
  20
  21         <para>
  22             The second argument <varname>$backendOptions</varname> is an optional
  23             backend options array.
  24         </para>
  25
  26         <programlisting language="php"><![CDATA[
  27 $backendOptions = array(
  28     'cache_dir' => './tmp/' // Directory where to put the swapped memory blocks
  29 );
  30
  31 $memoryManager = Zend_Memory::factory('File', $backendOptions);
  32 ]]></programlisting>
  33
  34         <para>
  35             <classname>Zend_Memory</classname> uses <link
  36                 linkend="zend.cache.backends"><classname>Zend_Cache backends</classname></link> as
  37             storage providers.
  38         </para>
  39
  40         <para>
  41             You may use the special name '<code>None</code>' as a backend name,
  42             in addition to standard <classname>Zend_Cache</classname> backends.
  43         </para>
  44
  45         <programlisting language="php"><![CDATA[
  46 $memoryManager = Zend_Memory::factory('None');
  47 ]]></programlisting>
  48
  49         <para>
  50             If you use '<code>None</code>' as the backend name, then the memory
  51             manager never swaps memory blocks. This is useful if you know that
  52             memory is not limited or the overall size of objects never reaches
  53             the memory limit.
  54         </para>
  55
  56         <para>
  57             The '<code>None</code>' backend doesn't need any option specified.
  58         </para>
  59     </sect2>
  60
  61     <sect2 id="zend.memory.memory-manager.objects-management">
  62         <title>Managing Memory Objects</title>
  63
  64         <para>
  65             This section describes creating and destroying objects in the
  66             managed memory, and settings to control memory manager behavior.
  67         </para>
  68
  69         <sect3 id="zend.memory.memory-manager.objects-management.movable">
  70             <title>Creating Movable Objects</title>
  71
  72             <para>
  73                 Create movable objects (objects, which may be swapped) using
  74                 the <methodname>Zend_Memory_Manager::create([$data])</methodname> method:
  75             </para>
  76
  77             <programlisting language="php"><![CDATA[
  78 $memObject = $memoryManager->create($data);
  79 ]]></programlisting>
  80
  81             <para>
  82                 The <varname>$data</varname> argument is optional and used to
  83                 initialize the object value. If the <varname>$data</varname>
  84                 argument is omitted, the value is an empty string.
  85             </para>
  86         </sect3>
  87
  88         <sect3 id="zend.memory.memory-manager.objects-management.locked">
  89             <title>Creating Locked Objects</title>
  90
  91             <para>
  92                 Create locked objects (objects, which are not swapped) using
  93                 the <methodname>Zend_Memory_Manager::createLocked([$data])</methodname> method:
  94             </para>
  95
  96             <programlisting language="php"><![CDATA[
  97 $memObject = $memoryManager->createLocked($data);
  98 ]]></programlisting>
  99
 100             <para>
 101                 The <varname>$data</varname> argument is optional and used to
 102                 initialize the object value. If the <varname>$data</varname>
 103                 argument is omitted, the value is an empty string.
 104             </para>
 105         </sect3>
 106
 107         <sect3 id="zend.memory.memory-manager.objects-management.destruction">
 108             <title>Destroying Objects</title>
 109
 110             <para>
 111                 Memory objects are automatically destroyed and removed from
 112                 memory when they go out of scope:
 113             </para>
 114
 115             <programlisting language="php"><![CDATA[
 116 function foo()
 117 {
 118     global $memoryManager, $memList;
 119
 120     ...
 121
 122     $memObject1 = $memoryManager->create($data1);
 123     $memObject2 = $memoryManager->create($data2);
 124     $memObject3 = $memoryManager->create($data3);
 125
 126     ...
 127
 128     $memList[] = $memObject3;
 129
 130     ...
 131
 132     unset($memObject2); // $memObject2 is destroyed here
 133
 134     ...
 135     // $memObject1 is destroyed here
 136     // but $memObject3 object is still referenced by $memList
 137     // and is not destroyed
 138 }
 139 ]]></programlisting>
 140
 141             <para>
 142                 This applies to both movable and locked objects.
 143             </para>
 144         </sect3>
 145     </sect2>
 146
 147     <sect2 id="zend.memory.memory-manager.settings">
 148         <title>Memory Manager Settings</title>
 149
 150         <sect3 id="zend.memory.memory-manager.settings.memory-limit">
 151             <title>Memory Limit</title>
 152
 153             <para>
 154                 Memory limit is a number of bytes allowed to be used by loaded
 155                 movable objects.
 156             </para>
 157
 158             <para>
 159                 If loading or creation of an object causes memory usage to
 160                 exceed of this limit, then the memory manager swaps some other
 161                 objects.
 162             </para>
 163
 164             <para>
 165                 You can retrieve or set the memory limit setting using the
 166                 <methodname>getMemoryLimit()</methodname> and
 167                 <methodname>setMemoryLimit($newLimit)</methodname> methods:
 168             </para>
 169
 170             <programlisting language="php"><![CDATA[
 171 $oldLimit = $memoryManager->getMemoryLimit();  // Get memory limit in bytes
 172 $memoryManager->setMemoryLimit($newLimit);     // Set memory limit in bytes
 173 ]]></programlisting>
 174
 175             <para>
 176                 A negative value for memory limit means 'no limit'.
 177             </para>
 178
 179             <para>
 180                 The default value is two-thirds of the value of
 181                 '<code>memory_limit</code>' in php.ini or 'no limit' (-1)
 182                 if '<code>memory_limit</code>' is not set in php.ini.
 183             </para>
 184         </sect3>
 185
 186         <sect3 id="zend.memory.memory-manager.settings.min-size">
 187             <title>MinSize</title>
 188
 189             <para>
 190                 MinSize is a minimal size of memory objects, which may be
 191                 swapped by memory manager. The memory manager does not swap
 192                 objects that are smaller than this value. This reduces the
 193                 number of swap/load operations.
 194             </para>
 195
 196             <para>
 197                 You can retrieve or set the minimum size using the
 198                 <methodname>getMinSize()</methodname> and
 199                 <methodname>setMinSize($newSize)</methodname> methods:
 200             </para>
 201
 202             <programlisting language="php"><![CDATA[
 203 $oldMinSize = $memoryManager->getMinSize();  // Get MinSize in bytes
 204 $memoryManager->setMinSize($newSize);        // Set MinSize limit in bytes
 205 ]]></programlisting>
 206
 207             <para>
 208                 The default minimum size value is 16KB (16384 bytes).
 209             </para>
 210         </sect3>
 211     </sect2>
 212 </sect1>