From f5b321df0214c8fa034aa55b3c008447bb773ae9 Mon Sep 17 00:00:00 2001 From: Zak Greant Date: Mon, 2 Jul 2001 03:03:43 +0000 Subject: [PATCH] Clarified declare/ticks documentation Made ticks a sect2 within declare's sect1 Added an illustrative example for ticks git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@50463 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/control-structures.xml | 359 +++++++++++++++++++------------- 1 file changed, 212 insertions(+), 147 deletions(-) diff --git a/language/control-structures.xml b/language/control-structures.xml index b8771d5297..7e8f6f15f5 100644 --- a/language/control-structures.xml +++ b/language/control-structures.xml @@ -68,7 +68,7 @@ if ($a > $b) { program. - + <literal>else</literal> @@ -101,7 +101,7 @@ if ($a > $b) { - + <literal>elseif</literal> @@ -149,7 +149,7 @@ if ($a > $b) { TRUE. - + Alternative syntax for control structures @@ -166,8 +166,8 @@ if ($a > $b) { PHP offers an alternative syntax for some of its control - structures; namely, if, - while, for, + structures; namely, if, + while, for, foreach, and switch. In each case, the basic form of the alternate syntax is to change the opening brace to a colon (:) and the closing brace to @@ -262,9 +262,9 @@ while ($i <= 10) { $i before the increment (post-increment) */ } - + /* example 2 */ - + $i = 1; while ($i <= 10): print $i; @@ -274,7 +274,7 @@ endwhile; - + <literal>do..while</literal> @@ -292,7 +292,7 @@ endwhile; There is just one syntax for do..while loops: - + $i = 0; @@ -340,7 +340,7 @@ do { `feature'. - + <literal>for</literal> @@ -386,22 +386,22 @@ for (expr1; expr2; expr3) statement /* example 1 */ - + for ($i = 1; $i <= 10; $i++) { print $i; } - + /* example 2 */ - + for ($i = 1;;$i++) { if ($i > 10) { break; } print $i; } - + /* example 3 */ - + $i = 1; for (;;) { if ($i > 10) { @@ -410,9 +410,9 @@ for (;;) { print $i; $i++; } - + /* example 4 */ - + for ($i = 1; $i <= 10; print $i, $i++) ; @@ -449,7 +449,7 @@ for (expr1; expr2; expr3): statement; ...; endfor; <literal>foreach</literal> PHP 4 (not PHP 3) includes a foreach construct, - much like perl and some other languages. This simply gives an easy + much like perl and some other languages. This simply gives an easy way to iterate over arrays. There are two syntaxes; the second is a minor but useful extension of the first: @@ -475,7 +475,7 @@ foreach(array_expression as $key => $value) statement When foreach first starts executing, the - internal array pointer is automatically reset to the first element + internal array pointer is automatically reset to the first element of the array. This means that you do not need to call reset before a foreach loop. @@ -585,7 +585,7 @@ foreach(array(1, 2, 3, 4, 5) as $v) { - + <literal>break</literal> @@ -596,7 +596,7 @@ foreach(array(1, 2, 3, 4, 5) as $v) { break accepts an optional numeric argument which tells it how many nested enclosing structures are to be - broken out of. + broken out of. @@ -628,7 +628,7 @@ while (++$i) { - + <literal>continue</literal> @@ -668,7 +668,7 @@ while ($i++ < 5) { - + <literal>switch</literal> @@ -678,7 +678,7 @@ while ($i++ < 5) { different values, and execute a different piece of code depending on which value it equals to. This is exactly what the switch statement is for. - + The following two examples are two different ways to write the same thing, one using a series of if @@ -695,7 +695,7 @@ if ($i == 1) { if ($i == 2) { print "i equals 2"; } - + switch ($i) { case 0: print "i equals 0"; @@ -823,47 +823,112 @@ endswitch; - + <literal>declare</literal> - - The declare statement is used to temporarily - change the state of the parser in a block of code. Here's how it looks: - + The declare construct is used to is + used to set execution directives for a block of code. + The syntax of declare is similiar to + the syntax of other flow control constructs: - -function tick() -{ - static $i; - printf("[tick i=%d]\n", ++$i); -} - -register_tick_function("tick"); - -declare (ticks = 2) { - 1; 2; 3; -} - + +declare (directive) statement + - This example shows the only implemented parser parameter today: - ticks. A tick is an event that occurs for every - N low-level statements executed by the - parser, where N is specified in the - declare statement. The example above will print: - [tick i=1] -[tick i=2] - + + + The directive section allows the + behavior of the declare block to + be set. + Currently only one directive is recognized: the + ticks directive. (See below for more + information on the + ticks + directive) + + + The statement part of the + declare block will be executed - how + it is executed and what side-effects occur during execution + may depend on the directive set in the + directive block. + + + Ticks + A tick is an event that occurs for every + N low-level statements executed + by the parser within the declare block. + The value for N is specified + using ticks=N + within the declare blocks's + directive section. + + + The event(s) that occurs on each tick is specified using the + register_tick_function. See the example + below for more details. Note that more than one event can occur + for each tick. + + + + Profile a section of PHP code + +<pre> +<?php +// A function that records the time when it is called +function profile ($dump = FALSE) +{ + static $profile; + + // Return the times stored in profile, then erase it + if ($dump) { + $temp = $profile; + unset ($profile); + return ($temp); + } + + $profile[] = microtime (); +} + +// Set up a tick handler +register_tick_function("profile"); + +// Initialize the function before the declare block +profile (); + +// Run a block of code, throw a tick every 2nd statement +declare (ticks=2) { + for ($x = 1; $x < 50; ++$x) { + echo similar_text (md5($x), md5($x*$x)), "<br>"; + } +} + +// Display the data stored in the profiler +print_r (profile (TRUE)); +?> +</pre> + + + The example profiles the PHP code within the 'declare' + block, recording the time at which every second low-level + statement in the block was executed. This information can + then be used to find the slow areas within particular + segments of code. This process can be performed using other + methods: using ticks is more convenient and easier to + implement. - Ticks is well suited for implementing simple multitasking, - backgrounded IO and many other things in PHP. + Ticks are well suited for debugging, implementing simple + multitasking, backgrounded I/O and many other tasks. See also register_tick_function and unregister_tick_function. + + <function>require</function> @@ -947,7 +1012,7 @@ require ('header.inc'); /* This example assumes that someserver is configured to parse .php - * files and not .txt files. Also, 'works' here means that the variables + * files and not .txt files. Also, 'works' here means that the variables * $varone and $vartwo are available within the require()ed file. */ /* Won't work; file.txt wasn't handled by someserver. */ @@ -955,10 +1020,10 @@ require ("http://someserver/file.txt?varone=1&vartwo=2"); /* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' * on the local filesystem. */ -require ("file.php?varone=1&vartwo=2"); +require ("file.php?varone=1&vartwo=2"); /* Works. */ -require ("http://someserver/file.php?varone=1&vartwo=2"); +require ("http://someserver/file.php?varone=1&vartwo=2"); $varone = 1; $vartwo = 2; @@ -979,10 +1044,10 @@ require ("file.php"); /* Works. */ See also include, require_once, include_once, readfile, - and virtual. + and virtual. - + <function>include</function> @@ -1038,14 +1103,14 @@ for ($i = 0; $i < count($files); $i++) { /* This is WRONG and will not work as desired. */ - + if ($condition) include($file); else include($other); - + /* This is CORRECT. */ - + if ($condition) { include($file); } else { @@ -1123,7 +1188,7 @@ Back in main.html However, PHP 3 will give the following output: -Before the return +Before the return 27Back in main.html Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5 @@ -1167,7 +1232,7 @@ Before the return /* This example assumes that someserver is configured to parse .php - * files and not .txt files. Also, 'works' here means that the variables + * files and not .txt files. Also, 'works' here means that the variables * $varone and $vartwo are available within the include()ed file. */ /* Won't work; file.txt wasn't handled by someserver. */ @@ -1175,10 +1240,10 @@ include ("http://someserver/file.txt?varone=1&vartwo=2"); /* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' * on the local filesystem. */ -include ("file.php?varone=1&vartwo=2"); +include ("file.php?varone=1&vartwo=2"); /* Works. */ -include ("http://someserver/file.php?varone=1&vartwo=2"); +include ("http://someserver/file.php?varone=1&vartwo=2"); $varone = 1; $vartwo = 2; @@ -1190,58 +1255,58 @@ include ("file.php"); /* Works. */ See also require, require_once, include_once, readfile, - and virtual. + and virtual. - + <function>require_once</function> The require_once statement replaces itself with the specified file, much like the C preprocessor's #include works, and in that respect is - similar to the require statement. The main - difference is that in an inclusion chain, the use of - require_once will assure that the code is - added to your script only once, and avoid clashes with variable - values or function names that can happen. + similar to the require statement. The main + difference is that in an inclusion chain, the use of + require_once will assure that the code is + added to your script only once, and avoid clashes with variable + values or function names that can happen. For example, if you create the following 2 include files - utils.inc and foolib.inc - - utils.inc - + utils.inc and foolib.inc + + utils.inc + <?php define(PHPVERSION, floor(phpversion())); echo "GLOBALS ARE NICE\n"; function goodTea() { - return "Oolong tea tastes good!"; + return "Oolong tea tastes good!"; } ?> - - - - foolib.inc - + + + + foolib.inc + <?php require ("utils.inc"); function showVar($var) { - if (PHPVERSION == 4) { - print_r($var); - } else { - var_dump($var); - } + if (PHPVERSION == 4) { + print_r($var); + } else { + var_dump($var); + } } // bunch of other functions ... ?> - - - And then you write a script cause_error_require.php - - cause_error_require.php - + + + And then you write a script cause_error_require.php + + cause_error_require.php + <?php require("foolib.inc"); /* the following will generate an error */ @@ -1253,45 +1318,45 @@ echo "Running goodTea: ".goodTea()."\n"; echo "Printing foo: \n"; showVar($foo); ?> - - - When you try running the latter one, the resulting ouptut will be (using - PHP 4.01pl2): - - + + + When you try running the latter one, the resulting ouptut will be (using + PHP 4.01pl2): + + GLOBALS ARE NICE GLOBALS ARE NICE Fatal error: Cannot redeclare goodTea() in utils.inc on line 5 - - - By modifying foolib.inc and - cause_errror_require.php - to use require_once - instead of require and renaming the - last one to avoid_error_require_once.php, we have: - - foolib.inc (fixed) - + + + By modifying foolib.inc and + cause_errror_require.php + to use require_once + instead of require and renaming the + last one to avoid_error_require_once.php, we have: + + foolib.inc (fixed) + ... require_once("utils.inc"); function showVar($var) { ... - - - - avoid_error_require_once.php - + + + + avoid_error_require_once.php + ... require_once("foolib.inc"); require_once("utils.inc"); $foo = array("1",array("complex","quaternion")); ... - - - And when running the latter, the output will be (using PHP 4.0.1pl2): - - + + + And when running the latter, the output will be (using PHP 4.0.1pl2): + + GLOBALS ARE NICE this is requiring globals.inc again which is also required in foolib.inc @@ -1307,53 +1372,53 @@ Array ) ) - - + + Also note that, analogous to the behavior of the - #include of the C preprocessor, this statement - acts at "compile time", e.g. when the script is parsed and before it - is executed, and should not be used for parts of the script that need - to be inserted dynamically during its execution. You should use - include_once or include - for that purpose. + #include of the C preprocessor, this statement + acts at "compile time", e.g. when the script is parsed and before it + is executed, and should not be used for parts of the script that need + to be inserted dynamically during its execution. You should use + include_once or include + for that purpose. - For more examples on using require_once and - include_once, look at the PEAR code included in - the latest PHP source code distributions. + For more examples on using require_once and + include_once, look at the PEAR code included in + the latest PHP source code distributions. See also: require, include, include_once, get_required_files, get_included_files, readfile, - and virtual. + and virtual. - + <function>include_once</function> The include_once statement includes and evaluates the specified file during the execution of the script. - This is a behavior similar to the include statement, - with the important difference that if the code from a file has already - been included, it will not be included again. + This is a behavior similar to the include statement, + with the important difference that if the code from a file has already + been included, it will not be included again. As mentioned in the require_once description, the - include_once should be used in the cases in which - the same file might be included and evaluated more than once during a - particular execution of a script, and you want to be sure that it is - included exactly once to avoid problems with function redefinitions, - variable value reassignments, etc. + include_once should be used in the cases in which + the same file might be included and evaluated more than once during a + particular execution of a script, and you want to be sure that it is + included exactly once to avoid problems with function redefinitions, + variable value reassignments, etc. - For more examples on using require_once and - include_once, look at the PEAR code included in - the latest PHP source code distributions. + For more examples on using require_once and + include_once, look at the PEAR code included in + the latest PHP source code distributions. include_once was added in PHP 4.0.1pl2 @@ -1363,12 +1428,12 @@ Array include, require_once, get_required_files, get_included_files, readfile, - and virtual. + and virtual. - + - + +-->