From 1b382d80a65fdd018cb7314dd68c424a96d2142f Mon Sep 17 00:00:00 2001
From: Stig Bakken <ssb@php.net>
Date: Mon, 21 May 2001 23:16:31 +0000
Subject: [PATCH] * documented "declare" and ticks

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@48118 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/funchand.xml          | 52 +++++++++++++++++++++++++++++++++
 language/control-structures.xml | 41 ++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)

diff --git a/functions/funchand.xml b/functions/funchand.xml
index 7e9544a523..ef5f66a7b2 100755
--- a/functions/funchand.xml
+++ b/functions/funchand.xml
@@ -561,6 +561,58 @@ Array
    </refsect1>
   </refentry>
   
+  <refentry id="function.register-tick-function">
+   <refnamediv>
+    <refname>register_tick_function</refname>
+    <refpurpose>
+     Register a function for execution on each tick
+    </refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <funcsynopsis>
+     <funcprototype>
+      <funcdef>void
+       <function>register_tick_function</function>
+      </funcdef>
+      <paramdef>string <parameter>func</parameter></paramdef>
+      <paramdef>mixed <parameter><optional>arg</optional></parameter>...</paramdef>
+     </funcprototype>
+    </funcsynopsis>
+    <simpara>
+     Registers the function named by <parameter>func</parameter> to be
+     executed when a <link
+     linkend="control-structures.declare">tick</link> is
+     called.</simpara>
+   </refsect1>
+  </refentry>
+  
+  <refentry id="function.unregister-tick-function">
+   <refnamediv>
+    <refname>unregister_tick_function</refname>
+    <refpurpose>
+     De-register a function for execution on each tick
+    </refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <funcsynopsis>
+     <funcprototype>
+      <funcdef>void
+       <function>unregister_tick_function</function>
+      </funcdef>
+      <paramdef>string <parameter>func</parameter></paramdef>
+      <paramdef>mixed <parameter><optional>arg</optional></parameter>...</paramdef>
+     </funcprototype>
+    </funcsynopsis>
+    <simpara>
+     De-registers the function named by <parameter>func</parameter> so it is
+     no longer executed when a <link
+     linkend="control-structures.declare">tick</link> is
+     called.</simpara>
+   </refsect1>
+  </refentry>
+  
  </reference>
 
 <!-- Keep this comment at the end of the file
diff --git a/language/control-structures.xml b/language/control-structures.xml
index f150ac2555..8b46c0c24f 100644
--- a/language/control-structures.xml
+++ b/language/control-structures.xml
@@ -432,6 +432,7 @@ for (expr1; expr2; expr3): statement; ...; endfor;
    </para>
 
   </sect1>
+
   <sect1 id="control-structures.foreach">
    <title><literal>foreach</literal></title>
    <para>
@@ -811,6 +812,46 @@ endswitch;
    </para>
   </sect1>
   
+  <sect1 id="control-structures.declare">
+   <title><literal>declare</literal></title>
+   <simpara>
+    The <literal>declare</literal> statement is used to temporarily
+    change the state of the parser in a block of code.  Here's how it looks:
+   </simpara>
+   <para>
+    <informalexample>
+     <programlisting role="php">
+function tick()
+{
+    static $i;
+    printf("[tick i=%d]\n", ++$i);
+}
+
+register_tick_function("tick");
+
+declare (ticks = 2) {
+    1; 2; 3;
+}
+</programlisting>
+    </informalexample>
+    This example shows the only implemented parser parameter today:
+    ticks.  A tick is an event that occurs for every
+    <replaceable>N</replaceable> low-level statements executed by the
+    parser, where <replaceable>N</replaceable> is specified in the
+    <literal>declare</literal> statement.  The example above will print:
+    <computeroutput>[tick i=1]
+[tick i=2]
+</computeroutput>
+   </para>
+   <simpara>
+    Ticks is well suited for implementing simple multitasking,
+    backgrounded IO and many other things in PHP.
+   </simpara>
+   <simpara>
+    See also <function>register_tick_function</function> and
+    <function>unregister_tick_function</function>.
+   </simpara>
+  </sect1>
   <sect1 id="function.require">
    <title><function>require</function></title>
    <simpara>