README.md

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

• Full API Documentation
• Official Twitter
• Gitter Chat

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();