README

ABOUT
	PowerSpawn is a PCNTL and POSIX wrapper for *nix systems running PHP
	
	It is for managing and running forked process for parrallel computing with PHP

NOTE
	PowerSpawn has been replaced by PowerProcess which can be found here: https://github.com/lordgnu/PowerProcess
	
	PowerProcess contains all the same features as PowerSpawn, but is easier to use and has more robust support
	of the PCNTL functions.  Additionally, PowerProcess allows simple daemonization of scripts and supports better
	socket-based logging

HOW TO USE
	First, be sure to include PowerSpawn in your source: require_once('/path/to/PowerSpawn.class.php')
	
	Then, you'll want to initialize the PowerSpawn Object and setup your config.  See the complete example below

EXAMPLE

<?php
// Include PowerSpawn
require_once('PowerSpawn.class.php');

// Initialize the object
$ps = new PowerSpawn;

// Create a callback function (Not required)
function allChildrenComplete() {
echo "All the children processes have completed\n";
}

function killedChild() {
echo "A child was just killed\n";
}

// Setup PowerSpawn Config
$ps->setCallback('allChildrenComplete'); // Calls the allChildrenComplete() function when all processes have checked in and there is no more work to complete
$ps->setKillCallback('killedChild'); // Calls the killedChild function when a child is executed for exceeding time limit
$ps->maxChildren = 5; // Only allows 5 children to be running at any given time
$ps->timeLimit = 10; // Kills children processes that run longer than 10 seconds

// Build an array with some fake data to proccess
$data = array();
for ($i = 0; $i < 15; $i++) {
$data[] = $i;
}

// Start the parent loop
while ($ps->runParentCode()) {
// Only the parent process will run code inside this loop

// Determine if we still have data to process
if (count($data)) {
// We still have data to process
// Check to see if we have an open slot to spawn a child
if ($ps->spawnReady()) {
// We can spawn a new process
$ps->childData = array_shift($data);

// Echo some text to let the user know that this is the parent and we are spawning a new child
echo "[PARENT] Spawning a new process\n";

// Spawn the process
$ps->spawnChild();
} else {
// All slots are full, just tick for now
$ps->Tick();
}
} else {
// There is no more data to process

// Echo some text to let the user know that the parent process is out of data
echo "[PARENT] Out of data to hand out - Waiting for all children to check in\n";

// Call the shutdown() method - blocks until all chilren have checked in or been killed because of executing too long
$ps->shutdown();

// All child processes have terminated
echo "[PARENT] All child processes have completed\n";
}
}

// Start the children code section
if ($ps->runChildCode()) {
// Only child processes forked by the parent will run this code
// The parent process will not execute this code

// Get the data for this run
$myNumber = $ps->childData;

// Let the user know the thread is running
echo "[CHILD:{$myNumber}] Running with number {$myNumber} - My PID is {$ps->myPID()}\n";

// Now we'll sleep x seconds where x is $myNumber - but we'll loop to show that we are doing work
$x = 0;
while ($x < $myNumber) {
sleep(1);
$x++;
echo "[CHILD:{$myNumber}] Just completed iteration {$x} of {$myNumber}\n";
}

// Let the user know that all work has been completed
// All children that run longer than 10 seconds won't make it this far with the settings above
echo "[CHILD:{$myNumber}] I have completed my work\n";
}


// Send signal 0 to let parent process know we are done
exit(0);

?>


OUPUT FROM EXAMPLE:
dbauer@zent:~/src/PowerSpawn$ php ./example.php 
PHP Deprecated:  Comments starting with '#' are deprecated in /etc/php5/cli/conf.d/mcrypt.ini on line 1 in Unknown on line 0
[PARENT] Spawning a new process
[PARENT] Spawning a new process
[CHILD:0] Running with number 0 - My PID is 22174
[CHILD:0] I have completed my work
[PARENT] Spawning a new process
[CHILD:1] Running with number 1 - My PID is 22175
[PARENT] Spawning a new process
[CHILD:2] Running with number 2 - My PID is 22176
[PARENT] Spawning a new process
[CHILD:3] Running with number 3 - My PID is 22177
[CHILD:4] Running with number 4 - My PID is 22178
[PARENT] Spawning a new process
[CHILD:5] Running with number 5 - My PID is 22179
[CHILD:1] Just completed iteration 1 of 1
[CHILD:1] I have completed my work
[CHILD:2] Just completed iteration 1 of 2
[CHILD:3] Just completed iteration 1 of 3
[CHILD:4] Just completed iteration 1 of 4
[PARENT] Spawning a new process
[CHILD:5] Just completed iteration 1 of 5
[CHILD:6] Running with number 6 - My PID is 22180
[CHILD:2] Just completed iteration 2 of 2
[CHILD:2] I have completed my work
[CHILD:3] Just completed iteration 2 of 3
[CHILD:4] Just completed iteration 2 of 4
[CHILD:5] Just completed iteration 2 of 5
[PARENT] Spawning a new process
[CHILD:6] Just completed iteration 1 of 6
[CHILD:7] Running with number 7 - My PID is 22181
[CHILD:3] Just completed iteration 3 of 3
[CHILD:3] I have completed my work
[CHILD:4] Just completed iteration 3 of 4
[CHILD:5] Just completed iteration 3 of 5
[CHILD:6] Just completed iteration 2 of 6
[CHILD:7] Just completed iteration 1 of 7
[PARENT] Spawning a new process
[CHILD:8] Running with number 8 - My PID is 22182
[CHILD:4] Just completed iteration 4 of 4
[CHILD:4] I have completed my work
[CHILD:5] Just completed iteration 4 of 5
[CHILD:6] Just completed iteration 3 of 6
[CHILD:7] Just completed iteration 2 of 7
[CHILD:8] Just completed iteration 1 of 8
[PARENT] Spawning a new process
[CHILD:9] Running with number 9 - My PID is 22183
[CHILD:5] Just completed iteration 5 of 5
[CHILD:5] I have completed my work
[CHILD:6] Just completed iteration 4 of 6
[CHILD:7] Just completed iteration 3 of 7
[CHILD:8] Just completed iteration 2 of 8
[CHILD:9] Just completed iteration 1 of 9
[PARENT] Spawning a new process
[CHILD:10] Running with number 10 - My PID is 22184
[CHILD:6] Just completed iteration 5 of 6
[CHILD:7] Just completed iteration 4 of 7
[CHILD:8] Just completed iteration 3 of 8
[CHILD:9] Just completed iteration 2 of 9
[CHILD:10] Just completed iteration 1 of 10
[CHILD:6] Just completed iteration 6 of 6
[CHILD:6] I have completed my work
[CHILD:7] Just completed iteration 5 of 7
[CHILD:8] Just completed iteration 4 of 8
[CHILD:9] Just completed iteration 3 of 9
[PARENT] Spawning a new process
[CHILD:10] Just completed iteration 2 of 10
[CHILD:11] Running with number 11 - My PID is 22185
[CHILD:7] Just completed iteration 6 of 7
[CHILD:8] Just completed iteration 5 of 8
[CHILD:9] Just completed iteration 4 of 9
[CHILD:10] Just completed iteration 3 of 10
[CHILD:11] Just completed iteration 1 of 11
[CHILD:7] Just completed iteration 7 of 7
[CHILD:7] I have completed my work
[CHILD:8] Just completed iteration 6 of 8
[CHILD:9] Just completed iteration 5 of 9
[PARENT] Spawning a new process
[CHILD:10] Just completed iteration 4 of 10
[CHILD:11] Just completed iteration 2 of 11
[CHILD:12] Running with number 12 - My PID is 22186
[CHILD:8] Just completed iteration 7 of 8
[CHILD:9] Just completed iteration 6 of 9
[CHILD:10] Just completed iteration 5 of 10
[CHILD:11] Just completed iteration 3 of 11
[CHILD:12] Just completed iteration 1 of 12
[CHILD:8] Just completed iteration 8 of 8
[CHILD:8] I have completed my work
[CHILD:9] Just completed iteration 7 of 9
[CHILD:10] Just completed iteration 6 of 10
[CHILD:11] Just completed iteration 4 of 11
[CHILD:12] Just completed iteration 2 of 12
[PARENT] Spawning a new process
[CHILD:13] Running with number 13 - My PID is 22188
[CHILD:9] Just completed iteration 8 of 9
[CHILD:10] Just completed iteration 7 of 10
[CHILD:11] Just completed iteration 5 of 11
[CHILD:12] Just completed iteration 3 of 12
[CHILD:13] Just completed iteration 1 of 13
[CHILD:9] Just completed iteration 9 of 9
[CHILD:9] I have completed my work
[CHILD:11] Just completed iteration 6 of 11
[CHILD:10] Just completed iteration 8 of 10
[CHILD:12] Just completed iteration 4 of 12
[CHILD:13] Just completed iteration 2 of 13
[PARENT] Spawning a new process
[PARENT] Out of data to hand out - Waiting for all children to check in
[CHILD:14] Running with number 14 - My PID is 22189
[CHILD:10] Just completed iteration 9 of 10
[CHILD:11] Just completed iteration 7 of 11
[CHILD:12] Just completed iteration 5 of 12
[CHILD:13] Just completed iteration 3 of 13
[CHILD:14] Just completed iteration 1 of 14
[CHILD:10] Just completed iteration 10 of 10
[CHILD:11] Just completed iteration 8 of 11
[CHILD:10] I have completed my work
[CHILD:12] Just completed iteration 6 of 12
[CHILD:13] Just completed iteration 4 of 13
A child was just killed
[CHILD:14] Just completed iteration 2 of 14
[CHILD:11] Just completed iteration 9 of 11
[CHILD:12] Just completed iteration 7 of 12
[CHILD:13] Just completed iteration 5 of 13
[CHILD:14] Just completed iteration 3 of 14
[CHILD:11] Just completed iteration 10 of 11
[CHILD:12] Just completed iteration 8 of 12
[CHILD:13] Just completed iteration 6 of 13
[CHILD:14] Just completed iteration 4 of 14
A child was just killed
[CHILD:12] Just completed iteration 9 of 12
[CHILD:13] Just completed iteration 7 of 13
[CHILD:14] Just completed iteration 5 of 14
[CHILD:12] Just completed iteration 10 of 12
[CHILD:13] Just completed iteration 8 of 13
[CHILD:14] Just completed iteration 6 of 14
A child was just killed
[CHILD:13] Just completed iteration 9 of 13
[CHILD:14] Just completed iteration 7 of 14
[CHILD:13] Just completed iteration 10 of 13
[CHILD:14] Just completed iteration 8 of 14
A child was just killed
[CHILD:14] Just completed iteration 9 of 14
[CHILD:14] Just completed iteration 10 of 14
A child was just killed
[PARENT] All child processes have completed
All the children processes have completed