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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.memory.overview">
   4     <title>Overview</title>
   5
   6     <sect2 id="zend.memory.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             The <classname>Zend_Memory</classname> component is intended to manage data in an
  11             environment with limited memory.
  12         </para>
  13
  14         <para>
  15             Memory objects (memory containers) are generated by memory manager
  16             by request and transparently swapped/loaded when it's necessary.
  17         </para>
  18
  19         <para>
  20             For example, if creating or loading a managed object would cause
  21             the total memory usage to exceed the limit you specify, some
  22             managed objects are copied to cache storage outside of memory.
  23             In this way, the total memory used by managed objects does not
  24             exceed the limit you need to enforce.
  25         </para>
  26
  27         <para>
  28             The memory manager uses
  29             <link linkend="zend.cache.backends">Zend_Cache backends</link>
  30             as storage providers.
  31         </para>
  32
  33         <example id="zend.memory.introduction.example-1">
  34             <title>Using Zend_Memory component</title>
  35
  36             <para>
  37                 <methodname>Zend_Memory::factory()</methodname> instantiates the memory
  38                 manager object with specified backend options.
  39             </para>
  40
  41             <programlisting language="php"><![CDATA[
  42 $backendOptions = array(
  43     'cache_dir' => './tmp/' // Directory where to put the swapped memory blocks
  44 );
  45
  46 $memoryManager = Zend_Memory::factory('File', $backendOptions);
  47
  48 $loadedFiles = array();
  49
  50 for ($count = 0; $count < 10000; $count++) {
  51     $f = fopen($fileNames[$count], 'rb');
  52     $data = fread($f, filesize($fileNames[$count]));
  53     $fclose($f);
  54
  55     $loadedFiles[] = $memoryManager->create($data);
  56 }
  57
  58 echo $loadedFiles[$index1]->value;
  59
  60 $loadedFiles[$index2]->value = $newValue;
  61
  62 $loadedFiles[$index3]->value[$charIndex] = '_';
  63 ]]></programlisting>
  64         </example>
  65     </sect2>
  66
  67     <sect2 id="zend.memory.theory-of-operation">
  68         <title>Theory of Operation</title>
  69
  70         <para>
  71             <classname>Zend_Memory</classname> component operates with the following concepts:
  72
  73             <itemizedlist>
  74                 <listitem>
  75                     <para>Memory manager</para>
  76                 </listitem>
  77
  78                 <listitem>
  79                     <para>Memory container</para>
  80                 </listitem>
  81
  82                 <listitem>
  83                     <para>Locked memory object</para>
  84                 </listitem>
  85
  86                 <listitem>
  87                     <para>Movable memory object</para>
  88                 </listitem>
  89             </itemizedlist>
  90         </para>
  91
  92         <sect3 id="zend.memory.theory-of-operation.manager">
  93             <title>Memory manager</title>
  94
  95             <para>
  96                 The memory manager generates memory objects (locked or movable)
  97                 by request of user application and returns them wrapped into
  98                 a memory container object.
  99             </para>
 100         </sect3>
 101
 102         <sect3 id="zend.memory.theory-of-operation.container">
 103             <title>Memory container</title>
 104
 105             <para>
 106                 The memory container has a virtual or actual <code>value</code>
 107                 attribute of string type. This attribute contains the data value
 108                 specified at memory object creation time.
 109             </para>
 110
 111             <para>
 112                 You can operate with this <code>value</code> attribute as
 113                 an object property:
 114
 115                 <programlisting language="php"><![CDATA[
 116 $memObject = $memoryManager->create($data);
 117
 118 echo $memObject->value;
 119
 120 $memObject->value = $newValue;
 121
 122 $memObject->value[$index] = '_';
 123
 124 echo ord($memObject->value[$index1]);
 125
 126 $memObject->value = substr($memObject->value, $start, $length);
 127 ]]></programlisting>
 128             </para>
 129
 130             <note>
 131                 <para>
 132                     If you are using a <acronym>PHP</acronym> version earlier than 5.2, use the
 133                     <link linkend="zend.memory.memory-objects.api.getRef">getRef()</link>
 134                     method instead of accessing the value property directly.
 135                 </para>
 136             </note>
 137         </sect3>
 138
 139         <sect3 id="zend.memory.theory-of-operation.locked">
 140             <title>Locked memory</title>
 141
 142             <para>
 143                 Locked memory objects are always stored in memory.
 144                 Data stored in locked memory are never swapped to the cache
 145                 backend.
 146             </para>
 147         </sect3>
 148
 149         <sect3 id="zend.memory.theory-of-operation.movable">
 150             <title>Movable memory</title>
 151
 152             <para>
 153                 Movable memory objects are transparently swapped and loaded
 154                 to/from the cache backend by <classname>Zend_Memory</classname> when it's necessary.
 155             </para>
 156
 157             <para>
 158                 The memory manager doesn't swap objects with size less than
 159                 the specified minimum, due to performance considerations.
 160                 See <xref linkend="zend.memory.memory-manager.settings.min-size" />
 161                 for more details.
 162             </para>
 163         </sect3>
 164     </sect2>
 165 </sect1>