README

PHP 5.5+ asynchronous cooperative task scheduler

Description

bubblr is a lightweight component that allows for cooperative multitasking without needing to understand generators or requiring code modification. bubblr allows multitasking using both functional and imperative programming paradigms.

Installation

Install via cli using composer:

php composer.phar require jgswift/bubblr:0.1.*

Install via composer.json using composer:

{
    "require": {
        "jgswift/bubblr": "0.1.*"
    }
}

Dependency

• php 5.5+
• jgswift/observr
• react/promise

Usage

Coroutine (Bubble)

Coroutines, or Bubbles (as they are referred to in this package) are units of work which are queued and executed. Any function or method can be wrapped by a coroutine to allow easy multitasking with minimal overhead.

BubbleInterface (abbr.)

interface BubbleInterface extends EventInterface, EventAwareInterface {

    public function getResult();

    public function setContext($context);

    public function resume(SpoutInterface $spout);

    public function suspend(SpoutInterface $spout);
}

Spouts

Spouts act as the scheduler queue to handle coroutine execution.
This is conceptually similar to a thread but must be differentiated as coroutines are executed in sequence. Coroutines may yield execution priority back to the spout, therein allowing other tasks to execute instead. For more information, Nikita Popov authored a fairly comprehesive introduction to the subject of cooperative multitasking in PHP.

SpoutInterface (abbr.)

interface SpoutInterface extends BubblerAwareInterface {

    public function push(BubbleInterface $bubble);

    public function pop();

    public function invoke(BubbleInterface $bubble);

    public function suspend();

    public function resume();
}

Core Bubbler

The core bubbler is the primary application that handles the creation and scheduling of spouts.

Coroutines, spouts, and the core are all open to modification using the globally aliased API.

BubblerInterface (abbr.)

interface BubblerInterface {

    public function execute($bubble = null);

    public function attach(SpoutInterface $spout);

    public function detach(SpoutInterface $spout);

    public function resume();

    public function suspend();

    public function getSpout();
}

Simple example (returning values)

$hello = bubblr\async(function() {
    return 'hello world';
});

echo $hello(); // 'hello world'

Scheduling existing methods

function hello() {
    return 'hello world';
}

$hello = bubblr\async('hello');

echo $hello(); // 'hello world'

Rescheduling during long-running task

$fib = bubblr\async(function($num) {
    $n1 = 0; $n2 = 1; $n3 = 1;
    for ($i = 2; $i < $num; ++$i) {
        $n3 = $n1 + $n2;
        $n1 = $n2;
        $n2 = $n3;
        // every 50 iterations this bubble will suspend and allow other waiting bubbles to execute
        if (!($i % 50)) { 
              bubblr\reschedule();
        }
    }
    return $n3;
});

echo is_infinite($fib(3000)); // true

Scheduling multiple coroutines at once

function hello() {
    return 'hello';
}

function world() {
    return 'world';
}

$results = bubblr\asyncAll([
    'hello',
    'world'
]);

var_dump($results); // Array ['hello','world']

Throwing and handling exceptions

$addition = bubblr\async(function($a,$b) {
    if(!is_numeric($a) || !is_numeric($b)) {
        throw new \InvalidArgumentException();
    }

    return $a + $b;
});

try {
    $addition('bar',5);
} catch(\InvalidArgumentException $e) {
    echo 'Invalid argument';
}