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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.memory.overview">
    <title>Overview</title>

    <sect2 id="zend.memory.introduction">
        <title>Introduction</title>

        <para>
            The <classname>Zend_Memory</classname> component is intended to manage data in an
            environment with limited memory.
        </para>

        <para>
            Memory objects (memory containers) are generated by memory manager
            by request and transparently swapped/loaded when it's necessary.
        </para>

        <para>
            For example, if creating or loading a managed object would cause
            the total memory usage to exceed the limit you specify, some
            managed objects are copied to cache storage outside of memory.
            In this way, the total memory used by managed objects does not
            exceed the limit you need to enforce.
        </para>

        <para>
            The memory manager uses
            <link linkend="zend.cache.backends">Zend_Cache backends</link>
            as storage providers.
        </para>

        <example id="zend.memory.introduction.example-1">
            <title>Using Zend_Memory component</title>

            <para>
                <methodname>Zend_Memory::factory()</methodname> instantiates the memory
                manager object with specified backend options.
            </para>

            <programlisting language="php"><![CDATA[
$backendOptions = array(
    'cache_dir' => './tmp/' // Directory where to put the swapped memory blocks
);

$memoryManager = Zend_Memory::factory('File', $backendOptions);

$loadedFiles = array();

for ($count = 0; $count < 10000; $count++) {
    $f = fopen($fileNames[$count], 'rb');
    $data = fread($f, filesize($fileNames[$count]));
    $fclose($f);

    $loadedFiles[] = $memoryManager->create($data);
}

echo $loadedFiles[$index1]->value;

$loadedFiles[$index2]->value = $newValue;

$loadedFiles[$index3]->value[$charIndex] = '_';
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.memory.theory-of-operation">
        <title>Theory of Operation</title>

        <para>
            <classname>Zend_Memory</classname> component operates with the following concepts:

            <itemizedlist>
                <listitem>
                    <para>Memory manager</para>
                </listitem>

                <listitem>
                    <para>Memory container</para>
                </listitem>

                <listitem>
                    <para>Locked memory object</para>
                </listitem>

                <listitem>
                    <para>Movable memory object</para>
                </listitem>
            </itemizedlist>
        </para>

        <sect3 id="zend.memory.theory-of-operation.manager">
            <title>Memory manager</title>

            <para>
                The memory manager generates memory objects (locked or movable)
                by request of user application and returns them wrapped into
                a memory container object.
            </para>
        </sect3>

        <sect3 id="zend.memory.theory-of-operation.container">
            <title>Memory container</title>

            <para>
                The memory container has a virtual or actual <property>value</property>
                attribute of string type. This attribute contains the data value
                specified at memory object creation time.
            </para>

            <para>
                You can operate with this <property>value</property> attribute as
                an object property:
            </para>

            <programlisting language="php"><![CDATA[
$memObject = $memoryManager->create($data);

echo $memObject->value;

$memObject->value = $newValue;

$memObject->value[$index] = '_';

echo ord($memObject->value[$index1]);

$memObject->value = substr($memObject->value, $start, $length);
]]></programlisting>

            <note>
                <para>
                    If you are using a <acronym>PHP</acronym> version earlier than 5.2, use the
                    <link linkend="zend.memory.memory-objects.api.getRef">getRef()</link>
                    method instead of accessing the value property directly.
                </para>
            </note>
        </sect3>

        <sect3 id="zend.memory.theory-of-operation.locked">
            <title>Locked memory</title>

            <para>
                Locked memory objects are always stored in memory.
                Data stored in locked memory are never swapped to the cache
                backend.
            </para>
        </sect3>

        <sect3 id="zend.memory.theory-of-operation.movable">
            <title>Movable memory</title>

            <para>
                Movable memory objects are transparently swapped and loaded
                to/from the cache backend by <classname>Zend_Memory</classname> when it's necessary.
            </para>

            <para>
                The memory manager doesn't swap objects with size less than
                the specified minimum, due to performance considerations.
                See <link linkend="zend.memory.memory-manager.settings.min-size">this section</link>
                for more details.
            </para>
        </sect3>
    </sect2>
</sect1>