icicleio / icicle Goto Github PK

Icicle is a PHP library for writing asynchronous code using synchronous coding techniques

License: MIT License

PHP 100.00%

icicle's Introduction

Icicle is now deprecated in favor of Amp v2.0. This version is is currently under development, but close to release. The v2.0 branches are amp_v2 in all packages except the main Amp package, loop package, and postgres package, where v2.0 is the master branch.

Icicle

Icicle is a PHP library for writing asynchronous code using synchronous coding techniques.

Icicle uses Coroutines built with Awaitables and Generators to facilitate writing asynchronous code using techniques normally used to write synchronous code, such as returning values and throwing exceptions, instead of using nested callbacks typically found in asynchronous code.

Library Components

Coroutines are interruptible functions for building asynchronous code using synchronous coding patterns and error handling.
Awaitables act as placeholders for future values of asynchronous operations. Awaitables can be yielded in coroutines to define interruption points. Callbacks registered with awaitables may return values and throw exceptions.
Observables represent asynchronous sets of values, providing operations usually associated with sets such as map, filter, and reduce. Observables also can be iterated over asynchronously within a coroutine.
Loop (event loop) is used to schedule functions, run timers, handle signals, and poll sockets for pending data or await for space to write.

Available Packages

Stream: Common coroutine-based interface for reading and writing data.
Socket: Asynchronous stream socket server and client.
Concurrent: Provides an easy to use interface for parallel execution with non-blocking communication and task execution.
DNS: Asynchronous DNS query executor, resolver and connector.
Filesystem: Asynchronous filesystem access.
HTTP: Asynchronous HTTP server and client.
WebSocket: Asynchronous WebSocket server and client.
React Adapter: Adapts the event loop and awaitables of Icicle to interfaces compatible with components built for React.

Documentation and Support

Requirements

PHP 5.5+ for v0.9.x branch (current stable) and v1.x branch (mirrors current stable)
PHP 7 for v2.0 (master) branch supporting generator delegation and return expressions

Installation

The recommended way to install Icicle is with the Composer package manager. (See the Composer installation guide for information on installing and using Composer.)

Run the following command to use Icicle in your project:

composer require icicleio/icicle

You can also manually edit composer.json to add Icicle as a project requirement.

// composer.json
{
    "require": {
        "icicleio/icicle": "^0.9"
    }
}

Suggested

pcntl extension: Enables custom signal handling.
ev extension: Extension providing the most performant event loop implementation.
uv extension (PHP 7 only): Another extension providing a more performant event loop implementation (experimental).

Example

The example script below demonstrates how awaitables can be yielded in a coroutine to create interruption points. Fulfillment values of awaitables are sent to the coroutine and rejection exceptions are thrown into the coroutine.

#!/usr/bin/env php
<?php

require dirname(__DIR__) . '/vendor/autoload.php';

use Icicle\Awaitable;
use Icicle\Coroutine\Coroutine;
use Icicle\Loop;

$generator = function () {
    try {
        // Sets $start to the value returned by microtime() after approx. 1 second.
        $start = (yield Awaitable\resolve(microtime(true))->delay(1));

        echo "Sleep time: ", microtime(true) - $start, "\n";

        // Throws the exception from the rejected promise into the coroutine.
        yield Awaitable\reject(new Exception('Rejected promise'));
    } catch (Exception $e) { // Catches promise rejection reason.
        echo "Caught exception: ", $e->getMessage(), "\n";
    }

    yield Awaitable\resolve('Coroutine completed');
};

$coroutine = new Coroutine($generator());

$coroutine->done(function ($data) {
    echo $data, "\n";
});

Loop\run();

icicle's People

Contributors

Stargazers

Watchers

icicle's Issues

PHP 7.0.2 and 7.0.3 Generator Bug

PHP 7.0.2 introduced a bug where a generator function with a return type declaration that returns from within a try/catch/finally block will not behave as expected. For example, the simple coroutine below should fulfill the coroutine with the integer 1 and print 1 in the finally block. PHP 7.0.2 will either crash, loop indefinitely, or otherwise behave oddly.

use Icicle\Coroutine;
use Icicle\Loop;

Coroutine\create(function (): \Generator {
    try {
        $value = 1;
        return yield $value;
    } finally {
        echo $value, PHP_EOL;
    }
})->done();

Loop\run();

This bug was fixed in php/php-src@001ce47. This fix will be in 7.0.4.

Coding around this bug should be straightforward. Remove the return type declaration or return outside the try/catch/finally block.

stream_select behaviour

In SelectLoop.php's call to stream_select the 'read' and 'write' arrays are populated such that the array keys are the integer cast of the resource id and the values are the resource itself. Usually the output from stream_select preserves the array keys and this is passed to pollManager->handle.

However I have found the array keys are not always preserved. In my testing with a single socket the key becomes 0 instead of the integer cast of the resource id. This breaks pollManager->handle, causing it to not find the socket. I cannot explain why it only happens sometimes.

The following debugging code added to SelectLoop.php's dispatch function can detect the problem in my application:
if ($count) {
/// begin insert debugging code ///
foreach ($read as $id => $resource) {
if ($id != (int) $resource) {
die("stream_select mismatch $id != $resource");
}
}
// end insert debugging code ////
}

The fix is to modify the 'handle' function in SelectIoManager.php.
Replacing:
foreach ($active as $id => $resource) {
...
With:
foreach ($active as $resource) {
$id = (int) $resource;
...

defunct not exit

have same icicle version (0.9.6) and have same cli code, 100%. one on ubuntu server, and other on centos server. using Fork:spawn and DefaultPool
on ubuntu server working fine,
but on centos server i got a lot of php <defunct> and makes cannot allocate memory, any suggestions ?

all extension is same on both server : ev extenstion, pcntl extension all same

Memory leak in Loop

I've found a memory leak inside the icicle loop when yielding from a co routine.

This can be replicated with the below code:

<?php

require_once("./vendor/autoload.php");

use Icicle\Loop;
use Icicle\Coroutine\Coroutine;

function gen()
{
    while(true){
        yield array_fill(0, 10000, 4);
        print memory_get_usage(false).PHP_EOL;
    }
}

Loop\immediate(
    function() {
        new Coroutine(gen());
    }
);

Loop\Run();

This is possibly related to https://bugs.php.net/bug.php?id=69887 and https://bugs.php.net/bug.php?id=62210 which is reported to be fixed in php7.1.

Fix PHP requirement in the Readme

The Readme says PHP 5.5.+, the real requirement is PHP 7.0+.

What is the best web framework for icicle to integrate in?

I am going to make a whatsapp-like app and I wonder which framework is most suitable for icicle?

SocketEvent raise exception for fd resource

The constructor of Icicle\Loop\Events\SocketEvent throws an Exception when $resource is an fd (int).
This error emerged whlle testing your react/loop integration with zeromq.

documentation in icicle.io domain is not available / parked

it seems the domain icicle.io is not hosting the documentation anymore, would be nice to move perhaps to github.io or some other place when the old one is not coming back

Fatal error: Class 'Icicle\Http\Client not found.

I tried to run example code, but getting Fatal error: Class 'Icicle\Http\Client not found exception.

composer.json

{
    "require": {
        "icicleio/icicle": "^0.9.6",
        "icicleio/http": "^0.3"
    }
}

PHP

>php -v
PHP 5.6.8 (cli) (built: Apr 15 2015 15:07:09)
Copyright (c) 1997-2015 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

Examplecode

<?php
require './vendor/autoload.php';
use Icicle\Coroutine;
use Icicle\Http;
use Icicle\Loop;
use Icicle\Stream;

Coroutine\create(function () {
    // Infinitely get input from the console until the user terminates the program.
    while (true) {
        // Read a line of text from standard input.
        // The program will block here, waiting for another line of input.
        $line = fgets(STDIN);

        // Trim extra newlines and whitespace.
        $url = trim($line);

        // Fetch the file at the given URL with an HTTP client.
        // We use a new coroutine here so that the download will run independently
        // of our loop.
        Coroutine\create(function () use ($url) {
            $client = new Http\Client();
            $response = (yield $client->request('GET', $url));

            // Collect the response body and write it to a file.
            $contents = (yield Stream\readAll($response->getBody()));
            $file = basename($url);
            file_put_contents($file, $contents);
        });
    }
});

// Run the event loop, as usual.
Loop\run();

PHP 5.4 using PHP 5.5 features

Hey friend,

https://github.com/icicleio/Icicle/blob/5797e370acb24e64c70494a35f4aad0f9de325c3/src/Coroutine/Coroutine.php#L132-L134

finally is a PHP 5.5 feature, but phpunit.xml.dist and composer.json both stipulate PHP 5.4 as a minimum version. Am I missing something or should the minimum version be bumped to 5.5?

Edit: also, generator syntax is (PHP 5 >= 5.5.0)

Ambiguous event extension description

This part of the documentation is very confusing. Which one is more performant?

event extension: Allows for the most performant event loop implementation.
libevent extension: Similar to the event extension, it allows for a more performant event loop implementation.

Icicle performance test

I have 2 download scripts async_downloader.php and downloader.php. Both are for getting the contents from URLs. First one is using Icicle co routine to increase the performance and the second one is a usual php loop. I have logged start time and end time of both the scripts, but there is no much performance difference I saw. Some times normal php script is faster than Icicle co routine. My codes are given below. Please advice me if I am missing anything in the scripts.

async_downloader.php

require './vendor/autoload.php';
use Icicle\Coroutine;
use Icicle\Loop;
use Icicle\Stream;
echo 'Start Time:' . date('Y-m-d H:i:s') . PHP_EOL;
Coroutine\create(function () {
    // Infinitely get input from the console until the user terminates the program.
    $i = 0;
    $url = [
        'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
        'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
        'http://github.com/icicleio',
        'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
        'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
        'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1',
        'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1',
        'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1',
        'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1'
    ];

    echo count($url) . PHP_EOL;
    while ($i <= count($url)) {
        // We use a new coroutine here so that the download will run independently
        // of our loop.
        Coroutine\create(function () use ($url, $i) {
            if (isset($url[$i]) && $url[$i] != '') {
                echo 'Processing ' . $url[$i] . PHP_EOL;
                $content = (yield file_get_contents($url[$i]));
                (yield file_put_contents($i . '.html', $content));
            }
        });
        $i++;
    }
});
echo 'End Time:' . date('Y-m-d H:i:s') . PHP_EOL;
// Run the event loop, as usual.
Loop\run();

downloader.php

echo 'Start Time:' . date('Y-m-d H:i:s') . PHP_EOL;
$i = 0;
$url = [
    'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
    'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
    'http://github.com/icicleio',
    'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
    'http://stackoverflow.com/questions/21700846/how-to-write-an-awaitable-method',
    'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1',
    'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1',
    'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1',
    'http://meta.stackoverflow.com/questions/333420/documentation-update-august-29th?cb=1'
];
while ($i <= count($url)) {

    if (isset($url[$i]) && $url[$i] != '') {
        echo 'Processing ' . $url[$i] . PHP_EOL;

        $content = (file_get_contents($url[$i]));
        (file_put_contents($i . '.html', $content));
    }
    $i++;
}
echo 'End Time:' . date('Y-m-d H:i:s') . PHP_EOL;

Fail to run the example code

I cd to the directory where test.php locate and run composer require icicle and then copy the example code. But all of the examples in readme are failed. Here is a piece of the example code:

<?php

require 'vendor/autoload.php';
use Icicle\Coroutine\Coroutine;
use Icicle\Dns\Executor\Executor;
use Icicle\Dns\Resolver\Resolver;
use Icicle\Loop;
use Icicle\Socket\Client\Connector;

$generator = function () {
    try {
        $resolver = new Resolver(new Executor('8.8.8.8'));

        // This coroutine pauses until yielded coroutine is fulfilled or rejected.
        $ips = (yield $resolver->resolve('example.com'));

        $connector = new Connector();

        // This coroutine pauses again until yielded coroutine is fulfilled or rejected.
        $client = (yield $connector->connect($ips[0], 80));

        echo "Asynchronously connected to example.com:80\n";
    } catch (Exception $exception) {
        echo "Asynchronous task failed: {$exception->getMessage()}\n";
    }
};

$coroutine = new Coroutine($generator());

Loop\run();
?>

And I got a Fetal error: Fatal error: Class 'Icicle\Dns\Resolver\Resolver' not found