README

This package was created to make it simple to create queues of tasks, such as for sending asynchronus MySQL queries or CURL requests.

Requirements

This package was built/tested using PHP 5.6. It may or may not work on earlier versions, but please be aware that any PHP version lower than 5.6 is deprecated.

The Queues

SerialRunnableQueue

Run items one after each other (FIFO), waiting for each one to complete before moving onto the next.

ParallelRunnableQueue

Run the items in parallel. These items could be executed/completed in any order. This is where performance benefits are realized.

RunnableStack

Execute items in the same manner as SerialRunnableQueue except that instead of being FIFO, items are executed in reverse order with the last item being added being executed first.

Interfaces

In order to use the queus, the objects you put into them need to implement the RunnableInterface which simply means the objects have a run method that returns true when the task has completed. This method will keep being called by the queue until it returns true. This may seem silly but is necessary for asynchronous requests which may take some time to complete, and thus you need to keep track of the state in the object and return true once you have the result back.

Queues Within Queues

Due to the fact that all of the queues also implement the RunnableInterface, you can create queues of other queues to create any combinations you need. For example, you may have several "tasks" that have to be executed in a certain order, however each of these "tasks" might consist of several hundred "sub-tasks" that can be executed in any order. In such a case, you would want to create a ParallelRunnableQueue to place each group of subtasks into. Then you would place each of these parallel queues into a single SerialRunnableQueue object to make sure the groups get executed in the correct order.

Every queue can take an optional callback in its constructor. This callback is executed whenever the queue is completed/emptied, allowing the developer to run logic only when the queu has finished.

Queues are not a fixed size, you can use the add method to add to them whenever you want, including whilst they are running. However, remember that the queu's callback will be invoked each time the queue is depleted.

Example Usage:

...

$asyncQuery1 = new \iRAP\AsyncQuery\AsyncQuery(
    $sql1,
    $queryCallback1,
    $connectionPool
);

$asyncQuery2 = new \iRAP\AsyncQuery\AsyncQuery(
    $sql2,
    $queryCallback2,
    $connectionPool2 # <-- different pool, perhaps for a different database?
);

$parallelRunnableQueue = new \iRAP\Queues\ParallelRunnableQueue($queueCallback);

$parallelRunnableQueue->add($asyncQuery1);
$parallelRunnableQueue->add($asyncQuery2);

# Run until the queue has completed all of the tasks.
while ($parallelRunnableQueue->run() !== TRUE)
{
    usleep(1);
}

Automated Tests

Simply go to the testing directory and execute the main.php script. All code contributions that add new functionality should provide a relevant test case. It may be a good idea to read through the automated tests to get example usages.

irap / queues

Maintainers

Details