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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.memory.memory-objects">
   4     <title>Memory Objects</title>
   5
   6     <sect2 id="zend.memory.memory-objects.movable">
   7         <title>Movable</title>
   8
   9         <para>
  10             Create movable memory objects using the <methodname>create([$data])</methodname>
  11             method of the memory manager:
  12         </para>
  13
  14         <programlisting language="php"><![CDATA[
  15 $memObject = $memoryManager->create($data);
  16 ]]></programlisting>
  17
  18         <para>
  19             "Movable" means that such objects may be swapped and unloaded from
  20             memory and then loaded when application code accesses the object.
  21         </para>
  22     </sect2>
  23
  24     <sect2 id="zend.memory.memory-objects.locked">
  25         <title>Locked</title>
  26
  27         <para>
  28             Create locked memory objects using the <methodname>createLocked([$data])</methodname>
  29             method of the memory manager:
  30         </para>
  31
  32         <programlisting language="php"><![CDATA[
  33 $memObject = $memoryManager->createLocked($data);
  34 ]]></programlisting>
  35
  36         <para>
  37             "Locked" means that such objects are never swapped and unloaded
  38             from memory.
  39         </para>
  40
  41         <para>
  42             Locked objects provides the same interface as movable objects
  43             (<classname>Zend_Memory_Container_Interface</classname>).
  44             So locked object can be used in any place instead of movable objects.
  45         </para>
  46
  47         <para>
  48             It's useful if an application or developer can decide, that some
  49             objects should never be swapped, based on performance considerations.
  50         </para>
  51
  52         <para>
  53             Access to locked objects is faster, because the memory manager doesn't
  54             need to track changes for these objects.
  55         </para>
  56
  57         <para>
  58             The locked objects class (<classname>Zend_Memory_Container_Locked</classname>)
  59             guarantees virtually the same performance as working with a string
  60             variable. The overhead is a single dereference to get the class property.
  61         </para>
  62     </sect2>
  63
  64     <sect2 id="zend.memory.memory-objects.value">
  65         <title>Memory container 'value' property</title>
  66
  67         <para>
  68             Use the memory container (movable or locked) '<code>value</code>'
  69             property to operate with memory object data:
  70         </para>
  71
  72         <programlisting language="php"><![CDATA[
  73 $memObject = $memoryManager->create($data);
  74
  75 echo $memObject->value;
  76
  77 $memObject->value = $newValue;
  78
  79 $memObject->value[$index] = '_';
  80
  81 echo ord($memObject->value[$index1]);
  82
  83 $memObject->value = substr($memObject->value, $start, $length);
  84 ]]></programlisting>
  85
  86         <para>
  87             An alternative way to access memory object data is to use the <link
  88                 linkend="zend.memory.memory-objects.api.getRef"><methodname>getRef()</methodname></link>
  89             method. This method <emphasis>must</emphasis> be used for <acronym>PHP</acronym>
  90             versions before 5.2. It also may have to be used in some other
  91             cases for performance reasons.
  92         </para>
  93     </sect2>
  94
  95     <sect2 id="zend.memory.memory-objects.api">
  96         <title>Memory container interface</title>
  97
  98         <para>
  99             Memory container provides the following methods:
 100         </para>
 101
 102         <sect3 id="zend.memory.memory-objects.api.getRef">
 103             <title>getRef() method</title>
 104
 105             <programlisting language="php"><![CDATA[
 106 public function &getRef();
 107 ]]></programlisting>
 108
 109             <para>
 110                 The <methodname>getRef()</methodname> method returns reference to the object value.
 111             </para>
 112
 113             <para>
 114                 Movable objects are loaded from the cache at this moment if the
 115                 object is not already in memory. If the object is loaded from
 116                 the cache, this might cause swapping of other objects if the
 117                 memory limit would be exceeded by having all the managed
 118                 objects in memory.
 119             </para>
 120
 121             <para>
 122                 The <methodname>getRef()</methodname> method <emphasis>must</emphasis> be
 123                 used to access memory object data for <acronym>PHP</acronym> versions before 5.2.
 124             </para>
 125
 126             <para>
 127                 Tracking changes to data needs additional resources.
 128                 The <methodname>getRef()</methodname> method returns reference to string,
 129                 which is changed directly by user application.
 130                 So, it's a good idea to use the <methodname>getRef()</methodname> method
 131                 for value data processing:
 132             </para>
 133
 134             <programlisting language="php"><![CDATA[
 135 $memObject = $memoryManager->create($data);
 136
 137 $value = &$memObject->getRef();
 138
 139 for ($count = 0; $count < strlen($value); $count++) {
 140     $char = $value[$count];
 141     ...
 142 }
 143 ]]></programlisting>
 144         </sect3>
 145
 146         <sect3 id="zend.memory.memory-objects.api.touch">
 147             <title>touch() method</title>
 148
 149             <programlisting language="php"><![CDATA[
 150 public function touch();
 151 ]]></programlisting>
 152
 153             <para>
 154                 The <methodname>touch()</methodname> method should be used in common with
 155                 <methodname>getRef()</methodname>. It signals that object value has been changed:
 156             </para>
 157
 158             <programlisting language="php"><![CDATA[
 159 $memObject = $memoryManager->create($data);
 160 ...
 161
 162 $value = &$memObject->getRef();
 163
 164 for ($count = 0; $count < strlen($value); $count++) {
 165     ...
 166     if ($condition) {
 167         $value[$count] = $char;
 168     }
 169     ...
 170 }
 171
 172 $memObject->touch();
 173 ]]></programlisting>
 174         </sect3>
 175
 176         <sect3 id="zend.memory.memory-objects.api.lock">
 177             <title>lock() method</title>
 178
 179             <programlisting language="php"><![CDATA[
 180 public function lock();
 181 ]]></programlisting>
 182
 183             <para>
 184                 The <methodname>lock()</methodname> methods locks object in memory.
 185                 It should be used to prevent swapping of some objects you choose.
 186                 Normally, this is not necessary, because the memory manager uses
 187                 an intelligent algorithm to choose candidates for swapping.
 188                 But if you exactly know, that at this part of code some
 189                 objects should not be swapped, you may lock them.
 190             </para>
 191
 192             <para>
 193                 Locking objects in memory also guarantees that reference
 194                 returned by the <methodname>getRef()</methodname> method is valid until you
 195                 unlock the object:
 196             </para>
 197
 198             <programlisting language="php"><![CDATA[
 199 $memObject1 = $memoryManager->create($data1);
 200 $memObject2 = $memoryManager->create($data2);
 201 ...
 202
 203 $memObject1->lock();
 204 $memObject2->lock();
 205
 206 $value1 = &$memObject1->getRef();
 207 $value2 = &$memObject2->getRef();
 208
 209 for ($count = 0; $count < strlen($value2); $count++) {
 210     $value1 .= $value2[$count];
 211 }
 212
 213 $memObject1->touch();
 214 $memObject1->unlock();
 215 $memObject2->unlock();
 216 ]]></programlisting>
 217         </sect3>
 218
 219         <sect3 id="zend.memory.memory-objects.api.unlock">
 220             <title>unlock() method</title>
 221
 222             <programlisting language="php"><![CDATA[
 223 public function unlock();
 224 ]]></programlisting>
 225
 226             <para>
 227                 <methodname>unlock()</methodname> method unlocks object when it's no longer
 228                 necessary to be locked. See the example above.
 229             </para>
 230         </sect3>
 231
 232         <sect3 id="zend.memory.memory-objects.api.isLocked">
 233             <title>isLocked() method</title>
 234
 235             <programlisting language="php"><![CDATA[
 236 public function isLocked();
 237 ]]></programlisting>
 238
 239             <para>
 240                 The <methodname>isLocked()</methodname> method can be used to check if
 241                 object is locked. It returns <constant>TRUE</constant> if the object
 242                 is locked, or <constant>FALSE</constant> if it is not locked.
 243                 This is always <constant>TRUE</constant> for "locked" objects,
 244                 and may be either <constant>TRUE</constant> or <constant>FALSE</constant>
 245                 for "movable" objects.
 246             </para>
 247         </sect3>
 248     </sect2>
 249 </sect1>