Download the PHP package mpyw/co without Composer

Co

Asynchronous cURL executor simply based on resource and Generator

The requests are executed as parallelly as possible :smile:
Note that there is only 1 process and 1 thread.

Table of Contents

• Installing
• API
  • Co::wait()
  • Co::async()
  • Co::isRunning()
  • Co::any() / Co::race() / Co::all()
  • Co::setDefaultOptions() / Co::getDefaultOptions()
• Rules
  • Conversion on Resolving
  • Exception-safe or Exception-unsafe Priority
  • Pseudo-sleep for Each Coroutine
  • Comparison with Generators of PHP7.0+ or PHP5.5~5.6
• Appendix
  • Timing Charts

Installing

Install via Composer.

And require Composer autoloader in your scripts.

API

Co::wait()

Wait for all the cURL requests to complete.
The options will override static defaults.

Arguments

• (mixed) $value
  Any values to be parallelly resolved.
• (array<string, mixed>) $options
  Associative array of options.

• Throwable which are not extended from RuntimeException, such as Error Exception LogicException are not captured. If you need to capture them, you have to write your own try-catch blocks in your functions.
• HTTP/1.1 pipelining can be used only if the TCP connection is already established and verified that uses keep-alive session. It means that the first bundle of HTTP/1.1 requests CANNOT be pipelined. You can use it from second yield in Co::wait() call.
• To use HTTP/2 multiplexing, you have to build PHP with libcurl 7.43.0+ and --with-nghttp2.
• To use autoschedule, PHP 7.0.7 or later is required.

When autoschedule Disabled:

• curl_multi_add_handle() call can be delayed.
• concurrency controlling with pipeline / multiplex CANNOT be correctly driven. You should set higher concurrency in those cases.

When autoschedule Enabled:

• curl_multi_add_handle() is always immediately called.
• CURLINFO_TOTAL_TIME CANNOT be correctly calculated. "Total Time" includes the time waiting for other requests are finished.

The details of CURLIFNO_*_TIME timing charts are described at the bottom of this page.

Return Value

(mixed)
Resolved values; in exception-safe context, it may contain...

• CURLException which has been raised internally.
• RuntimeException which has been raised by user.

Exception

• Throws CURLException or RuntimeException in exception-unsafe context.

Co::async()

Execute cURL requests along with Co::wait() call, without waiting resolved values.
The options are inherited from Co::wait().

This method is mainly expected to be used ...

• When you are not interested in responses.
• In CURLOPT_WRITEFUNCTION or CURLOPT_HEADERFUNCTION callbacks.

Arguments

• (mixed) $value
  Any values to be parallelly resolved.
• (mixed) $throw
  Overrides throw in Co::wait() options when you passed true or false.

Return Value

(null)

Exception

• CURLException or RuntimeException can be thrown in exception-unsafe context.
  Note that you CANNOT capture top-level exceptions unless you catch outside of Co::wait() call.

Co::isRunning()

Return if Co::wait() is running().
With this check, you can safely call Co::wait() or Co::async().

Co::any()
Co::race()
Co::all()

Return a Generator that resolves with specific value.

• Jobs CANNOT be canceled.
  Incomplete jobs remain even if Co::any() or Co::race() is resolved.
• Co::all(...) is just a wrapper of (function () { return yield ...; })().
  It should be only used with Co::race() or Co::any().

Co::setDefaultOptions()
Co::getDefaultOptions()

Overrides/gets static default settings.

Rules

Conversion on Resolving

The all yielded/returned values are resolved by the following rules.
Yielded values are also resent to the Generator.
The rules will be applied recursively.

"Generator Closure" means Closure that contains yield keywords.

Exception-safe or Exception-unsafe Priority

Context in Generator

Exception-unsafe context by default.
The following yield statement specifies exception-safe context.

This is equivalent to:

Context on Co::wait()

Exception-unsafe context by default.
The following setting specifies exception-safe context.

This is equivalent to:

Context on Co::async()

Contexts are inherited from Co::wait().
The following setting overrides parent context as exception-safe.

The following setting overrides parent context as exception-unsafe.

Pseudo-sleep for Each Coroutine

The following yield statements delay the coroutine processing:

Comparison with Generators of PHP7.0+ or PHP5.5~5.6

return Statements

PHP 7.0+:

PHP 5.5~5.6:

Although experimental aliases Co::RETURN_ Co::RET Co::RTN are provided,
Co::RETURN_WITH is recommended in terms of readability.

yield Statements with Assignment

PHP 7.0+:

PHP 5.5~5.6:

finally Statements

Be careful that return triggers finally while yield Co::RETURN_WITH => does not.

Appendix

Timing Charts

Note that S is equal to Q when autoschedule is disabled.

Basic

With Redirections by CURLOPT_FOLLOWLOCATION