Class PHP_Fork

Description

PHP_Fork class. Wrapper around the pcntl_fork() stuff with a API set like Java language.

Practical usage is done by extending this class, and re-defining the run() method. Example:


1 class executeThread extends PHP_Fork {
2 var $counter;
3
4 function executeThread($name)
5 {
6 $this->PHP_Fork($name);
7 $this->counter = 0;
8 }
9
10 function run()
11 {
12 $i = 0;
13 while ($i < 10) {
14 print time() . "-(" . $this->getName() . ")-" . $this->counter++ . "\n";
15 sleep(1);
16 $i++;
17 }
18 }
19 }

This way PHP developers can enclose logic into a class that extends PHP_Fork, then execute the start() method that forks a child process. Communications with the forked process is ensured by using a Shared Memory Segment; by using a user-defined signal and this shared memory developers can access to child process methods that returns a serializable variable.

The shared variable space can be accessed with the tho methods:

  • void setVariable($name, $value)
  • mixed getVariable($name)
$name must be a valid PHP variable name; $value must be a variable or a serializable object. Resources (db connections, streams, etc.) cannot be serialized and so they're not correctly handled.

Requires PHP build with --enable-cli --with-pcntl --enable-shmop.
Only runs on *NIX systems, because Windows lacks of the pcntl ext.

Located in Program_Root/Fork.php (line 83)



			
Method Summary
bool PHP_Fork (string $name, integer $puid, integer $guid, [integer $umask = -1])
integer getLastAlive ()
string getName ()
integer getPid ()
mixed getVariable (mixed $name)
boolean isRunning ()
void register_callback_func ($arglist $arglist, $methodname $methodname)
void run ()
void setAlive ()
void setName ($name $name)
void setVariable (mixed $name, mixed $value)
void start ()
boolean stop ()
Methods
Constructor PHP_Fork (line 215)

PHP_Fork::PHP_Fork() Allocates a new pseudo-thread object and set its name to $name.

Optionally, set a PUID, a GUID and a UMASK for the child process. This also initialize Shared Memory Segments for process communications.

Supposing that you've defined the executeThread class as above, creating the pseudo-threads instances is very simple:


1 ...
2 $executeThread1 = new executeThread ("executeThread-1");
3 $executeThread2 = new executeThread ("executeThread-2");
4 ...
The pseudo-thread name must be unique; you can create and start as many pseudo-threads as you want; the limit is (of course) system resources.

  • return: true if the Shared Memory Segments are OK, false otherwise.
    Notice that only if shared mem is ok the process will be forked.
  • access: public
bool PHP_Fork (string $name, integer $puid, integer $guid, [integer $umask = -1])
  • string $name: The name of this pseudo-thread; must be unique between PHP processes running on the same server.
  • integer $puid: Owner of the forked process; if none, the user will be the same that created the pseudo-thread
  • integer $guid: Group of the forked process; if none, the group will be the same of the user that created the pseudo-thread
  • integer $umask: the umask of the new process; if none, the umask will be the same of the user that created the pseudo-thread
getLastAlive (line 311)

PHP_Fork::getLastAlive()

Read the time elapsed since the last child setAlive() call.

This method is useful because often we have a pseudo-thread pool and we need to know each pseudo-thread status. if the child executes the setAlive() method, the parent with getLastAlive() can know that child is alive.

integer getLastAlive ()
getName (line 328)

PHP_Fork::getName() Returns this pseudo-thread's name.

string getName ()
getPid (line 340)

PHP_Fork::getPid() Return the PID of the current pseudo-thread.

  • return: the PID.
integer getPid ()
getVariable (line 275)

PHP_Fork::getVariable()

Get a variable from the shared memory segment

mixed getVariable (mixed $name)
isRunning (line 245)

PHP_Fork::isRunning() Test if the pseudo-thread is already started.

A pseudo-thread that is instantiated but not started only exist as an instance of PHP_Fork class into parent process; no forking is done until the start() method is called.

  • return: true is the child is already forked.
boolean isRunning ()
register_callback_func (line 354)

PHP_Fork::register_callback_func()

This is called from within the parent method; all the communication stuff is done here...

void register_callback_func ($arglist $arglist, $methodname $methodname)
  • $arglist $arglist
  • $methodname $methodname
run (line 417)

PHP_Fork::run()

This method actually implements the pseudo-thread logic.
Subclasses of PHP_Fork MUST override this method as v.0.2

  • abstract:
void run ()
setAlive (line 293)

PHP_Fork::setAlive()

Set a pseudo-thread property that can be read from parent process in order to know the child activity.

Practical usage requires that child process calls this method at regular time intervals; parent will use the getLastAlive() method to know the elapsed time since the last pseudo-thread life signals...

void setAlive ()
setName (line 430)

PHP_Fork::setName() Changes the name of this thread to the given name.

void setName ($name $name)
  • $name $name
setVariable (line 261)

PHP_Fork::setVariable()

Set a variable into the shared memory segment so that it can accessed both from the parent & from the child process.

void setVariable (mixed $name, mixed $value)
start (line 451)

PHP_Fork::start() Causes this pseudo-thread to begin parallel execution.


1 ...
2 $executeThread1->start();
3 ...

This method check first of all the Shared Memory Segment; if ok, if forks the child process, attach signal handler and returns immediatly. The status is set to running, and a PID is assigned. The result is that two pseudo-threads are running concurrently: the current thread (which returns from the call to the start() method) and the other thread (which executes its run() method).

void start ()
stop (line 501)

PHP_Fork::stop() Causes the current thread to die.


1 ...
2 $executeThread1->stop();
3 ...

The relative process is killed and disappears immediately from the processes list.

  • return: true if the process is succesfully stopped, false otherwise.
boolean stop ()

Documentation generated on Tue, 9 Dec 2003 10:46:02 +0100 by phpDocumentor 1.2.2