search for in the  
<switchreturn>
Last updated: Thu, 19 May 2005

declare

The declare construct is used to set execution directives for a block of code. The syntax of declare is similar to the syntax of other flow control constructs: 

declare (directive)
    statement

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.

The declare construct can also be used in the global scope, affecting all code following it.

<?php
// these are the same:

// you can use this:
declare(ticks=1) {
   // entire script here
}

// or you can use this:
declare(ticks=1);
// entire script here
?>

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 occur on each tick are specified using the register_tick_function(). See the example below for more details. Note that more than one event can occur for each tick.

Example 16-3. Profile a section of PHP code

<?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));
?>
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 are well suited for debugging, implementing simple multitasking, background I/O and many other tasks.

See also register_tick_function() and unregister_tick_function().



User Contributed Notes
declare
chris-at-free-source.com
28-Feb-2005 02:16
Also note that PHP is run in a single thread and so everything it does will be one line of code at a time.  I'm not aware of any true threading support in PHP, the closest you can get is to fork.

so, declare tick doens't "multi-thread" at all, it is simply is a way to automaticaly call a function every n-lines of code.
19-Jan-2005 12:40
Just to point out that many webservers have multiple CPUs or hyperthreading, so they can indeed execute several threads in parallel without context switching.
Docey
02-Dec-2004 07:44
i want to make a short not that many think multi-tasking is not working as expected, but actualy this is expected.

multi-tasking / multi-treading does not run paralel as many think. its actualy a constant switching between 2 or more treads. this has to do with the fact there is only 1 cpu. and 1 cpu can only execute one command at the time. every os works this way, linux, windows, even mac.

the only thing here is that os are written in C++ and PHP first has to be translated into C++ calls before executed. thats why PHP will never be as fast as C++ code and thus you will note the switching as a delay. thinking it does not run paralel but at this very moment your os is switching between diffrent treads with about 1 million switches every seconds where php may only achief 40.000 a second.

so when designing some multi-tasking system you must expect a system that constantly switches form task about every 20 tick for example. this will give the idea that the system is executing multiple thinks at the same time while actualy switching between them every 20 ticks.

hope this clears things up for some people trying to design a multi-treaded / multi-tasking system just as me.

most important: keep the switching code to a minimum. this is executed as wel between every switching treads.
fok at nho dot com dot br
07-Jul-2003 08:45
This is a very simple example using ticks to execute a external script to show rx/tx data from the server

<?php

function traf(){
  passthru( './traf.sh' );
  echo "<br />\n";
  flush(); // keeps it flowing to the browser...
  sleep( 1 );
}

register_tick_function( "traf" );

declare( ticks=1 ){
  while( true ){}  // to keep it running...
}

?>

contents of traf.sh:
# Shows TX/RX for eth0 over 1sec
#!/bin/bash

TX1=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $9}'`
RX1=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $1}'`
sleep 1
TX2=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $9}'`
RX2=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $1}'`

echo -e "TX: $[ $TX2 - $TX1 ] bytes/s \t RX: $[ $RX2 - $RX1 ] bytes/s"
#--= the end. =--
daniel@swn
01-Feb-2003 01:56
<?php
ob_end_clean();
ob_implicit_flush(1);

function a() {
 for($i=0;$i<=100000;$i++) { }
 echo "function a() ";
}
function b() {
 for($i=0;$i<=100000;$i++) { }
 echo "function b() ";
}

register_tick_function ("a");
register_tick_function ("b");

declare (ticks=4)
{
   while(true)
   {
       sleep(1);
       echo "\n<br><b>".time()."</b><br>\n";;
   }
}
?>
You will see that a() and b() are slowing down this process. They are in fact not executed every second as expected. So this function is not a real alternative for multithreading using some slow functions..there is no difference to this way: while (true) { a(); b(); sleep(1); }
xxoes
08-Jan-2003 04:23
If i use ticks i must declare all functions before i call the function.

example:

Dosn't work
<?php
function ticks() {
   echo "tick";
}
register_tick_function("ticks");

declare (ticks=1) 1;

echo "";
echo "";

foo(); // Call to undefined function.

function foo() {
   echo "foo";
}
?>

Work
<?php
function ticks() {
   echo "tick";
}
register_tick_function("ticks");

//declare (ticks=1) 1;

echo "";
echo "";

foo();

function foo() {
   echo "foo";
}
?>

win2k : PHP 4.3.0 (cgi-fcgi)
rob_spamsux at rauchmedien dot ihatespam dot com
19-Mar-2002 04:45
Correction to above note:

Apparently, the end brace '}' at the end of the statement causes a tick.

So using

------------
declare (ticks=1) echo "1 tick after this prints";
------------

gives the expected behavior of causing 1 tick.

Note: the tick is issued after the statement executes.

Also, after playing around with this, I found that it is not really the multi-tasking I had expected. It behaves the same as simply calling the functions. I.e. each function must finish before passing the baton to the next function. They do not run in parallel.

It also seems that they always run in the order in which they were registered.

So,

<?php
------------
# register tick functions
register_tick_function ("a");
register_tick_function ("b");

# make the tick functions run
declare (ticks=1);
?>
------------

is equivalent to

------------
a();
b();
------------

It is simply a convenient way to have functions called periodically while some other code is being executed. I.e. you could use it to periodically check the status of something and then exit the script or do something else based on the status.
rob_spamsux at rauchmedien dot ihatespam dot com
19-Mar-2002 03:58
Here is an example of multi-tasking / multi-threading:

<?php
# declare functions
function a() {
  echo "a";
}
function b() {
  echo "b";
}

# register tick functions
register_tick_function ("a");
register_tick_function ("b");

# make the tick functions run
declare (ticks=1);

# that's all there is to it.
?>

Notes:
This will make functions a and b run once each at the same time.

If you try:

declare (ticks=1) {
  1;
}

They will run twice each. That is because it seems to be an undocumented fact that there is always an extra tick.

Therefore:

declare (ticks=2) {
  1;
}

Will cause them to run once.

<switchreturn>
 Last updated: Thu, 19 May 2005
Copyright © 2001-2005 The PHP Group
All rights reserved.		 This unofficial mirror is operated at: The Server Pages
Last updated: Thu May 19 17:35:34 2005 CDT