Download the PHP package choval/async without Composer

Choval\Async

A library to ease handling promises in ReactPHP.

• Install
• Usage
• License
• Functions
  • async Run blocking code in async mode
  • execute Execute a command
  • is_done Instantly return if the Promise is resolved or rejected
  • resolve Use yield with promises!
  • retry Retry a function multiple times
  • silent Silently resolve
  • sleep Non-blocking sleep
  • timeout Adds a timeout to a Promise
  • timer Allows to time a Promise
  • wait Make async code synchronous
  • wait_memory Waits for a number of RAM bytes to be available
  • PHP file functions PHP's blocking file functions in async mode

Install

Requirements

• PHP 8.0+
• for async & execute:
  • ext-pcntl
  • ext-posix
  • ext-sockets

Usage

Having the following function

The ugly way:

Using yield, remember future() is returning a Promise.
And we're not blocking other events in the loop ;-)

Or in a while-loop

Functions

is_done

Checks if a Promise has been resolved or rejected. This returns a boolean, not a Promise.

resolve

This is what will let you yield promises, it's like Node.js await.

Take for example the following async events.

$promise resolves with hello world in 1 sec, despite the second promise resolving first.

What if you need to run multiple async simultaneously?

Memory usage

silent

Similar to resolve, but will catch any Exception and save it in the second parameter.
If it fails, the promise will resolve with null.

execute

Executes a command asynchronously.
Returns a Promise with the output of the command.

A timeout parameter (in seconds) can be passed.

sleep

An asynchronous sleep function. This won't block other events.

Remember this is a non-blocking sleep, if you do not wait for it or yield inside an Async\resolve, the Promise will solve in the background.

wait

Also knowsn as sync, makes asynchronous code blocking. Use this when you need to use an async library in a sync/blocking scenario.

This function receives one of the following: Generator, Closure or PromiseInterface.

A second float parameter is a timeout in seconds, defaults to no timeout.

A third float parameter is the interval at which to check, defaults to 0.01 secs. A low interval will consume much more CPU.

async

Have a piece of blocking code that you need to run in async? Use this, just keep in mind it is using pcntl_fork.

First parameter is a callable, second parameter is an array of parameters for the callable.

There's a limit of 50 simultaneously running async forks. This limit can be changed by calling Async\set_forks_limit.
This limit is counted for Async\execute as well.

When the limit is reached, the code will wait for any previous fork to finish before continuing, keeping a max of async forks at the set forks limit.

retry

Runs a function (Closure/Generator) up to retries times for a "good" return. Otherwise, returns the last Exception.
This function can also ignore a set of Exception classes or messages.

timeout

Similar to React\Promise\Timer\timeout(), but allows a Generator or Closure too.

timer

Saves the number of elapsed microseconds (float).

wait_memory

Waits for a number of memory bytes to be available.
This is used inside loops to avoid memory exhaution due to multiple Promises being created and left in background.

A second parameter can be passed for the frequency to run the check.
Returns the number of bytes remaining (memory_limit - memory_get_usage()).

rglob

A recursive glob with an ignore parameter.

Consider the following files:

PHP file functions

The following functions are available with the same parameters as their PHP versions, but run using Async\async and take an optional LoopInterface as their first parameter.

These are not production tested/optimized. Please use with caution.

Example:

License

MIT, see LICENSE.