php-doc-en/internals2/counter.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <part xml:id="internals2.counter" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>The "counter" Extension - A Continuing Example</title>
  
  <partintro xml:id="internals2.counter.preface">
   <title>Preface</title>
   <simpara> 
    Throughout this Zend documentation, references are made to an example module
    in order to illustrate various concepts. The "counter" extension is this
    example, a fictional yet functional Zend module which strives to use as much
    of the Zend API as is reasonably possible. This short chapter describes the
    userland interface to the completed extension.
   </simpara>
  
   <note>
    <simpara>
     "counter" serves no practical purpose whatsoever, as the functionality it
     provides is far more effectively implemented by appropriate userland code.
    </simpara>
   </note>
  </partintro>
  
  <chapter xml:id="internals2.counter.setup">
   &reftitle.setup;

   <section xml:id="internals2.counter.intro">
    &reftitle.intro;
  
    <simpara>
     The "counter" extension provides any number of counters to PHP code using it
     which reset at times determined by the caller.
    </simpara>
   
    <simpara>
     There are three interfaces to "counter": basic, extended, and objective. The
     basic interface provides a single counter controlled by INI settings and
     function calls. The extended interface provides an arbitrary number of named
     counter resources which may optionally persist beyond the lifetime of a
     single PHP request. The objective interface combines both the basic and
     extended interfaces into a <classname>Counter</classname> class.
    </simpara>
   </section>
  
   <section xml:id="internals2.counter.ini">
    &reftitle.runtime;

    &extension.runtime;
    <table>
     <title>Counter configuration options</title>
     <tgroup cols="4">
      <thead>
       <row>
        <entry>Name</entry>
        <entry>Default</entry>
        <entry>Changeable</entry>
        <entry>Changelog</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>counter.reset_time</entry>
        <entry>COUNTER_RESET_PER_REQUEST</entry>
        <entry>PHP_INI_ALL</entry>
        <entry></entry>
       </row>
       <row>
        <entry>counter.save_path</entry>
        <entry>""</entry>
        <entry>PHP_INI_ALL</entry>
        <entry></entry>
       </row>
       <row>
        <entry>counter.initial_value</entry>
        <entry>"0"</entry>
        <entry>PHP_INI_ALL</entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    <simpara>&ini.php.constants;</simpara>

    <variablelist>
     <varlistentry xml:id="internals2.counter.ini.reset-time">
      <term>
       <parameter>counter.reset_time</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <simpara>
        <varname>counter.reset_time</varname> tells "counter" to reset the
        counter used by the basic interface. It may be any of the
        <constant>COUNTER_RESET_*</constant> constants (see below).
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry xml:id="internals2.counter.ini.save-path">
      <term>
       <parameter>counter.save_path</parameter>
       <type>string</type>
      </term>
      <listitem>
       <simpara>
        Tells "counter" where to save data that has to persist between
        invocations of PHP (i.e. any counter that has COUNTER_RESET_NEVER or
        COUNTER_FLAG_SAVE). A file will be created at this path, which must be
        readable and writable to whatever user PHP is running as.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry xml:id="internals2.counter.ini.initial-value">
      <term>
       <parameter>counter.initial_value</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <simpara>
        Sets the initial value of the counter used by the basic interface
        whenever it is reset.
       </simpara>
      </listitem>
     </varlistentry>
    </variablelist>

   </section>

   <section xml:id="internals2.counter.resources">
    &reftitle.resources;
   
    <simpara>
     The "counter" extension defines one resource type: a counter.
    </simpara>
   </section>

  </chapter>
  
  <appendix xml:id="internals2.counter.constants">
   &reftitle.constants;
   &extension.constants;

   <variablelist>
    <varlistentry>
     <term>
      <constant>COUNTER_FLAG_PERSIST</constant>
      (<type>integer</type>)
     </term>
     <listitem>
      <simpara>
       A counter with this flag will be created as a persistent resource.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_FLAG_SAVE</constant>
      (<type>integer</type>)
     </term>
     <listitem>
      <simpara>
       A counter with this flag will be saved between invocations of PHP.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_FLAG_NO_OVERWRITE</constant>
      (<type>integer</type>)
     </term>
     <listitem>
      <simpara>
       This flag causes <function>counter_create</function> to avoid overwriting
       an existing named counter with a new one.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_META_NAME</constant>
      (<type>string</type>)
     </term>
     <listitem>
      <simpara>
       Pass this constant to get the name of a counter resource or object.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_META_IS_PERISTENT</constant>
      (<type>string</type>)
     </term>
     <listitem>
      <simpara>
       Pass this constant to determine whether a counter resource or object is
       persistent (has the <constant>COUNTER_FLAG_PERSIST</constant> flag).
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_RESET_NEVER</constant>
      (<type>integer</type>)
     </term>
     <listitem>
      <simpara>
       The counter will never be reset.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_RESET_PER_LOAD</constant>
      (<type>integer</type>)
     </term>
     <listitem>
      <simpara>
       The counter will be reset on each invocation of PHP.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>COUNTER_RESET_PER_REQUEST</constant>
      (<type>integer</type>)
     </term>
     <listitem>
      <simpara>
       The counter will be reset on each request.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </appendix>

  <chapter xml:id="internals2.counter.examples">
   &reftitle.examples;
   
   <section xml:id="internals2.counter.examples.basic">
    <title>Basic interface</title>
    
    <simpara>
     The basic interface provides three simple functions, illustrated here:
    </simpara>
   
    <example xml:id="internals2.counter.examples.basic.ex">
     <title>"counter"'s basic interface</title>
     <programlisting role="php">
<![CDATA[
<?php
$starting_counter_value = counter_get();
counter_bump(1);
$second_counter_value = counter_get();
counter_reset();
$final_counter_value = counter_get();
printf("%3d %3d %3d", $starting_counter_value, $second_counter_value, $final_counter_value);
?>
]]>
     </programlisting>
    </example>
    &example.outputs;
    <screen>
<![CDATA[
  0   1   0]]></screen>
   
    <simpara>
     The basic interface also provides a number of
     <link linkend="internals2.counter.constants">INI settings</link>.
    </simpara>
   </section>
   
   <section xml:id="internals2.counter.examples.extended">
    <title>Extended interface</title>
    
    <simpara>
     The extended interface provides a small suite of functions that allow the
     user to define an arbitrary number of named counters with unique settings.
     The basic interface can be used in parallel with the extended interface.
    </simpara>
    
    <example xml:id="internals2.counter.examples.extended.ex">
     <title>"counter"'s extended interface</title>
     <programlisting role="php">
<![CDATA[
<?php
function print_counter_info($counter)
{
    if (is_resource($counter)) {
        printf("Counter's name is '%s' and is%s persistent. Its current value is %d.\n",
            counter_get_meta($counter, COUNTER_META_NAME),
            counter_get_meta($counter, COUNTER_META_IS_PERSISTENT) ? '' : ' not',
            counter_get_value($counter));
    } else {
      print "Not a valid counter!\n";
    }
}

if (($counter_one = counter_get_named("one")) === NULL) {
    $counter_one = counter_create("one", 0, COUNTER_FLAG_PERSIST);
}
counter_bump_value($counter_one, 2);
$counter_two = counter_create("two", 5);
$counter_three = counter_get_named("three");
$counter_four = counter_create("four", 2, COUNTER_FLAG_PERSIST | COUNTER_FLAG_SAVE | COUNTER_FLAG_NO_OVERWRITE);
counter_bump_value($counter_four, 1);

print_counter_info($counter_one);
print_counter_info($counter_two);
print_counter_info($counter_three);
print_counter_info($counter_four);
?>
]]>
     </programlisting>
     <simpara>
      When run once, the above example outputs:
     </simpara>
     <screen>
<![CDATA[
Counter's name is 'one' and is persistent. Its current value is 2.
Counter's name is 'two' and is not persistent. Its current value is 5.
Not a valid counter!
Counter's name is 'four' and is persistent. Its current value is 3.]]></screen>
     <simpara>
      If run a second time within the same instance of PHP, it outputs:
     </simpara>
     <screen>
<![CDATA[
Counter's name is 'one' and is persistent. Its current value is 4.
Counter's name is 'two' and is not persistent. Its current value is 5.
Not a valid counter!
Counter's name is 'four' and is persistent. Its current value is 4.]]></screen>
     <simpara>
      If then run a third time <emphasis>in a different instance of
      PHP</emphasis>, it outputs:
     </simpara>
     <screen>
<![CDATA[
Counter's name is 'one' and is persistent. Its current value is 2.
Counter's name is 'two' and is not persistent. Its current value is 5.
Not a valid counter!
Counter's name is 'four' and is persistent. Its current value is 5.]]></screen>
    </example>
   </section>
   
   <section xml:id="internals2.counter.examples.objective">
    <title>Objective interface</title>
    
    <simpara>
     The objective interface provides an object-oriented way to access the
     extended interfaces. The following example shows how the above one would be
     implemented using the objective interface. The output of this example is
     exactly the same, except that instead of printing "Not a valid counter!",
     this will instead issue a PHP warning that the variable
     <literal>$counter_three</literal> is not an object. This example shows that
     it is possible to subclass the <classname>Counter</classname> class defined
     by the extension, as well as that the counter's value is maintained using
     an instance variable rather than method access.
    </simpara>
    
    <example xml:id="internals2.counter.examples.objective.ex">
     <title>"counter"'s objective interface</title>
     
     <programlisting role="php">
<![CDATA[
<?php
class MyCounter extends Counter
{
    public function printCounterInfo() {
        printf("Counter's name is '%s' and is%s persistent. Its current value is %d.\n",
            $this->getMeta(COUNTER_META_NAME),
            $this->getMeta(COUNTER_META_IS_PERSISTENT) ? '' : ' not',
            $this->value);
    }
}

Counter::setCounterClass("MyCounter");
if (($counter_one = Counter::getNamed("one")) === NULL) {
    $counter_one = new Counter("one", 0, COUNTER_FLAG_PERSIST);
}
$counter_one->bumpValue(2); // we aren't allowed to "set" the value directly
$counter_two = new Counter("two", 5);
$counter_three = Counter::getNamed("three");
$counter_four = new Counter("four", 2, COUNTER_FLAG_PERSIST | COUNTER_FLAG_SAVE | COUNTER_FLAG_NO_OVERWRITE);
$counter_four->bumpValue(1);

$counter_one->printCounterInfo();
$counter_two->printCounterInfo();
$counter_three->printCounterInfo();
$counter_four->printCounterInfo();
?>
]]>
     </programlisting>
    </example>
   </section>

  </chapter>
  
  <reference xml:id="internals2.counter.counter-class">
   <title>The Counter class</title>
   <titleabbrev>Counter</titleabbrev>
   
   <partintro>
    <section xml:id="internals2.counter.counter-class.intro">
     &reftitle.intro;
     <simpara>
      Represents a single counter object.
     </simpara>
    </section>
   
    <section xml:id="internals2.counter.counter-class.synopsis">
     &reftitle.classsynopsis;
     
     <classsynopsis>
      <ooclass><classname>Counter</classname></ooclass>
     
      <classsynopsisinfo>
       <ooclass><classname>Counter</classname></ooclass>
      </classsynopsisinfo>
 
      <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('internals2.counter.counter-class')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[1])" />
      <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('internals2.counter.counter-class')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
     </classsynopsis>
    </section>
   </partintro>
   
   <refentry xml:id="internals2.counter.counter-class.construct" role="noversion">
    <refnamediv>
     <refname>Counter::__construct</refname>
     <refpurpose>
      Creates an instance of a Counter which maintains a single numeric value.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <constructorsynopsis>
      <methodname>Counter::__construct</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
      <methodparam choice="opt"><type>integer</type><parameter>initial_value</parameter></methodparam>
      <methodparam choice="opt"><type>integer</type><parameter>flags</parameter></methodparam>
     </constructorsynopsis>
     <simpara>
      Creates an instance of a Counter which maintains a single numeric value.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term>name</term>
       <listitem>
        <simpara>
         The new counter's name.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>initial_value</term>
       <listitem>
        <simpara>
         The initial value of the counter. Defaults to zero (0).
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>flags</term>
       <listitem>
        <simpara>
         Flags for the new counter, chosen from the
         <literal>COUNTER_FLAG_*</literal> constants.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      Returns a Counter object on success.
     </simpara>
    </refsect1>
    <refsect1 role="errors">
     &reftitle.errors;
     <simpara>
      <function>Counter::__construct</function> throws an Exception if something
      goes wrong.
     </simpara>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.counter-class.getvalue" role="noversion">
    <refnamediv>
     <refname>Counter::getValue</refname>
     <refpurpose>
      Get the current value of a counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>integer</type><methodname>Counter::getValue</methodname>
      <void/>
     </methodsynopsis>
     <simpara>
      <function>Counter::getValue</function> returns the current value of a
      counter.
     </simpara>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>Counter::getValue</function> returns an integer.
     </simpara>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>Counter::bumpValue</function></member>
      <member><function>Counter::resetValue</function></member>
     </simplelist>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.counter-class.bumpvalue" role="noversion">
    <refnamediv>
     <refname>Counter::bumpValue</refname>
     <refpurpose>
      Change the current value of a counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <methodname>Counter::bumpValue</methodname>
      <methodparam><type>integer</type><parameter>offset</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>Counter::bumpValue</function> updates the current value of a
      counter.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>offset</parameter></term>
       <listitem>
        <simpara>
         The amount by which to change the counter's value. Can be negative.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>Counter::getValue</function></member>
      <member><function>Counter::resetValue</function></member>
     </simplelist>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.counter-class.resetvalue" role="noversion">
    <refnamediv>
     <refname>Counter::resetValue</refname>
     <refpurpose>
      Reset the current value of a counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <void /><methodname>Counter::resetValue</methodname>
      <void/>
     </methodsynopsis>
     <simpara>
      <function>Counter::resetValue</function> resets the current value of a
      counter to its original initial value.
     </simpara>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>Counter::getValue</function></member>
      <member><function>Counter::bumpValue</function></member>
     </simplelist>
    </refsect1>
   </refentry>
   
   <refentry xml:id="internals2.counter.counter-class.getmeta" role="noversion">
    <refnamediv>
     <refname>Counter::getMeta</refname>
     <refpurpose>
      Return a piece of metainformation about a counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>mixed</type><methodname>Counter::getMeta</methodname>
      <methodparam><type>integer</type><parameter>attribute</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>Counter::getMeta</function> returns metainformation about a
      counter.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>attribute</parameter></term>
       <listitem>
        <simpara>
         The metainformation to retrieve.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>Counter::getMeta</function> returns values of varying types
      based on which metainformation was requested.
     </simpara>
    </refsect1>
   </refentry>
   
   <refentry xml:id="internals2.counter.counter-class.getnamed" role="noversion">
    <refnamediv>
     <refname>Counter::getNamed</refname>
     <refpurpose>
      Retrieve an existing named counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <modifier>static</modifier>
      <type>Counter</type><methodname>Counter::getNamed</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>Counter::getNamed</function> returns an existing counter by name
      if that name exists, or &null; otherwise. This is a static function.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>name</parameter></term>
       <listitem>
        <simpara>
         The counter name to search for.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>Counter::getNamed</function> returns an existing counter by name
      if that name exists, or &null; otherwise.
     </simpara>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.counter-class.setcounterclass" role="noversion">
    <refnamediv>
     <refname>Counter::setCounterClass</refname>
     <refpurpose>
      Set the class returned by <methodname>Counter::getNamed</methodname>.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <modifier>static</modifier>
      <void /><methodname>Counter::setCounterClass</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>Counter::setCounterClass</function> changes the class of objects
      returned by <function>Counter::getNamed</function>. The class being set
      must not have a public constructor and must be a subclass of
      <classname>Counter</classname>. If these conditions are not met, a fatal
      error is raised. This is a static function.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>name</parameter></term>
       <listitem>
        <simpara>
         The name of the class to use.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
   </refentry>

  </reference>
  
  <reference xml:id="internals2.counter.basic-interface">
   <title>The basic interface</title>
   <titleabbrev>Basic</titleabbrev>

   <refentry xml:id="internals2.counter.function.counter-get" role="noversion">
    <refnamediv>
     <refname>counter_get</refname>
     <refpurpose>
      Get the current value of the basic counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>integer</type><methodname>counter_get</methodname>
      <void/>
     </methodsynopsis>
     <simpara>
      <function>counter_get</function> returns the current value of the basic
      interface's counter.
     </simpara>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>counter_get</function> returns an integer.
     </simpara>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>counter_bump</function></member>
      <member><function>counter_reset</function></member>
     </simplelist>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.function.counter-bump" role="noversion">
    <refnamediv>
     <refname>counter_bump</refname>
     <refpurpose>
      Update the current value of the basic counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <void /><methodname>counter_bump</methodname>
      <methodparam><type>integer</type><parameter>offset</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>counter_bump</function> updates the current value of the basic
      interface's counter.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>offset</parameter></term>
       <listitem>
        <simpara>
         The amount by which to change the counter's value. Can be negative.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>counter_get</function></member>
      <member><function>counter_reset</function></member>
     </simplelist>
    </refsect1>
   </refentry>
  
   <refentry xml:id="internals2.counter.function.counter-reset" role="noversion">
    <refnamediv>
     <refname>counter_reset</refname>
     <refpurpose>
      Reset the current value of the basic counter.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <void /><methodname>counter_reset</methodname>
      <void/>
     </methodsynopsis>
     <simpara>
      <function>counter_reset</function> resets the current value of the basic
      interface's counter to its original initial value.
     </simpara>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>counter_get</function></member>
      <member><function>counter_bump</function></member>
     </simplelist>
    </refsect1>
   </refentry>

  </reference>

  <reference xml:id="internals2.counter.extended-interface">
   <title>The extended interface</title>
   <titleabbrev>Extended</titleabbrev>

   <refentry xml:id="internals2.counter.function.counter-create" role="noversion">
    <refnamediv>
     <refname>counter_create</refname>
     <refpurpose>
      Creates a counter which maintains a single numeric value.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>resource</type><methodname>counter_create</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
      <methodparam choice="opt"><type>integer</type><parameter>initial_value</parameter></methodparam>
      <methodparam choice="opt"><type>integer</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      Creates a counter which maintains a single numeric value.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term>name</term>
       <listitem>
        <simpara>
         The new counter's name.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>initial_value</term>
       <listitem>
        <simpara>
         The initial value of the counter. Defaults to zero (0).
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>flags</term>
       <listitem>
        <simpara>
         Flags for the new counter, chosen from the
         <literal>COUNTER_FLAG_*</literal> constants.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      Returns a counter resource.
     </simpara>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.function.counter-get-value" role="noversion">
    <refnamediv>
     <refname>counter_get_value</refname>
     <refpurpose>
      Get the current value of a counter resource.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>integer</type><methodname>counter_get_value</methodname>
      <methodparam><type>resource</type><parameter>counter</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>counter_get_value</function> returns the current value of a
      counter resource.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>counter</parameter></term>
       <listitem> 
        <simpara>
         The counter resource to operate on.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>counter_get_value</function> returns an integer.
     </simpara>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>counter_bump_value</function></member>
      <member><function>counter_reset_value</function></member>
     </simplelist>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.function.counter-bump-value" role="noversion">
    <refnamediv>
     <refname>counter_bump_value</refname>
     <refpurpose>
      Change the current value of a counter resource.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <void /><methodname>counter_bump_value</methodname>
      <methodparam><type>resource</type><parameter>counter</parameter></methodparam>
      <methodparam><type>integer</type><parameter>offset</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>counter_bump_value</function> updates the current value of a
      counter resource.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>counter</parameter></term>
       <listitem> 
        <simpara>
         The counter resource to operate on.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>offset</parameter></term>
       <listitem>
        <simpara>
         The amount by which to change the counter's value. Can be negative.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>counter_get_value</function></member>
      <member><function>counter_reset_value</function></member>
     </simplelist>
    </refsect1>
   </refentry>

   <refentry xml:id="internals2.counter.function.counter-reset-value" role="noversion">
    <refnamediv>
     <refname>counter_reset_value</refname>
     <refpurpose>
      Reset the current value of a counter resource.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <void /><methodname>counter_reset_value</methodname>
      <methodparam><type>resource</type><parameter>counter</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>counter_reset_value</function> resets the current value of a
      counter resource to its original initial value.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>counter</parameter></term>
       <listitem> 
        <simpara>
         The counter resource to operate on.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="seealso">
     &reftitle.seealso;
     <simplelist>
      <member><function>counter_get_value</function></member>
      <member><function>counter_bump_value</function></member>
     </simplelist>
    </refsect1>
   </refentry>
   
   <refentry xml:id="internals2.counter.function.counter-get-meta" role="noversion">
    <refnamediv>
     <refname>counter_get_meta</refname>
     <refpurpose>
      Return a piece of metainformation about a counter resource.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>mixed</type><methodname>counter_get_meta</methodname>
      <methodparam><type>resource</type><parameter>counter</parameter></methodparam>
      <methodparam><type>integer</type><parameter>attribute</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>counter_get_meta</function> returns metainformation about a
      counter resource.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>counter</parameter></term>
       <listitem> 
        <simpara>
         The counter resource to operate on.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>attribute</parameter></term>
       <listitem>
        <simpara>
         The metainformation to retrieve.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>counter_get_meta</function> returns values of varying types
      based on which metainformation was requested.
     </simpara>
    </refsect1>
   </refentry>
   
   <refentry xml:id="internals2.counter.function.counter-get-named" role="noversion">
    <refnamediv>
     <refname>counter_get_named</refname>
     <refpurpose>
      Retrieve an existing named counter as a resource.
     </refpurpose>
    </refnamediv>
    <refsect1 role="description">
     &reftitle.description;
     <methodsynopsis>
      <type>resource</type><methodname>Counter::getNamed</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
     <simpara>
      <function>counter_get_named</function> returns an existing counter by name
      if that name exists, or &null; otherwise.
     </simpara>
    </refsect1>
    <refsect1 role="parameters">
     &reftitle.parameters;
     <variablelist>
      <varlistentry>
       <term><parameter>name</parameter></term>
       <listitem>
        <simpara>
         The counter name to search for.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </refsect1>
    <refsect1 role="returnvalues">
     &reftitle.returnvalues;
     <simpara>
      <function>counter_get_name</function> returns an existing counter by name
      if that name exists, or &null; otherwise.
     </simpara>
    </refsect1>
   </refentry>

  </reference>

 </part>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->