Documentation update

[programarivm]

Hi there,

I'm new to amphp/parallel. Please correct me if wrong, but it seems as if the README needs to be updated.

The example below will throw an error:

<?php

require __DIR__  . '/../../vendor/autoload.php';

use Amp\Future;
use Amp\Parallel\Worker;
use function Amp\async;

use ChessServer\FetchTask;

$urls = [
    'https://secure.php.net',
    'https://amphp.org',
    'https://github.com',
];

$executions = [];
foreach ($urls as $url) {
    // FetchTask is just an example, you'll have to implement
    // the Task interface for your task.
    $executions[$url] = Worker\submit(new FetchTask($url));
}

// Each submission returns an Execution instance to allow two-way
// communication with a task. Here we're only interested in the
// task result, so we use the Future from Execution::getFuture()
$responses = Future\await(array_map(
    fn (Worker\Execution $e) => $e->getFuture(),
    $executions,
));

foreach ($responses as $url => $response) {
    \printf("Read %d bytes from %s\n", \strlen($response), $url);
}

PHP Fatal error:  Uncaught Error: Call to undefined function Amp\Parallel\Worker\submit()

Also an error is thrown if the following example is run:

<?php

require __DIR__  . '/../../vendor/autoload.php';

use Amp\Parallel\Worker;
use ChessServer\FetchTask;

$worker = Worker\createWorker();
$task = new FetchTask('https://amphp.org');

$execution = $worker->submit($task);

$data = $execution->await();

PHP Fatal error:  Uncaught Error: Call to undefined function Amp\Parallel\Worker\createWorker()

Thanks for the help and keep up the great work!

[trowski]

Hi @programarivm!

These two examples are working for me. Be sure that your path to autoload.php is correct so that the functions.php file where these functions are defined can be loaded.

[programarivm]

Sorry @trowski, it seems as if the documentation is not detailed enough. Or perhaps I am missing something? Let me rephrase the question.

I am getting the following error when trying to run the Hello World example.

php cli/amphp/hello-world.php 
PHP Fatal error:  Uncaught Error: Call to undefined function Amp\async() in /home/standard/projects/chesslablab/chess-server/cli/amphp/hello-world.php:9
Stack trace:
#0 {main}
  thrown in /home/standard/projects/chesslablab/chess-server/cli/amphp/hello-world.php on line 9

👉 What do I need to do specifically for the "Hello world" example to work as expected?

PHP Fatal error:  Uncaught Error: Call to undefined function Amp\async()

🙏 Thank you for the help.

[kelunik]

Did you run composer require amphp/amp?

[programarivm]

Yes, that's the thing. I am just following the instructions in the docs.

[programarivm]

Hi there,

👍 I can confirm that the docs examples work for me in a fresh install using version ^3.0 for amphp/amp so you may want to close this issue.

mkdir foo
standard@standard:~/projects/chesslablab$ cd foo
standard@standard:~/projects/chesslablab/foo$ composer require amphp/amp
./composer.json has been created
Running composer update amphp/amp
Loading composer repositories with package information
Updating dependencies
Lock file operations: 2 installs, 0 updates, 0 removals
  - Locking amphp/amp (v3.0.2)
  - Locking revolt/event-loop (v1.0.6)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 2 installs, 0 updates, 0 removals
  - Installing revolt/event-loop (v1.0.6): Extracting archive
  - Installing amphp/amp (v3.0.2): Extracting archive
A connection timeout was encountered. If you intend to run Composer without connecting to the internet, run the command again prefixed with COMPOSER_DISABLE_NETWORK=1 to make Composer run in offline mode.
Generating autoload files
1 package you are using is looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found.
Using version ^3.0 for amphp/amp
standard@standard:~/projects/chesslablab/foo$ php hello-world.php 
Let's start: Hello World from the future!

However, if running the exact same command in the chesslablab/chess-server repository, it is version ^2.6 what will be installed instead of ^3.0.

composer require amphp/amp
./composer.json has been updated
Running composer update amphp/amp
Loading composer repositories with package information
Updating dependencies                                 
Nothing to modify in lock file
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 0 installs, 0 updates, 1 removal
  - Removing revolt/event-loop (v1.0.6)
Generating autoload files
65 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found.
Using version ^2.6 for amphp/amp

Thus, if specifying the package version the following problems will occur:

composer require amphp/amp:3.0.2
./composer.json has been updated
Running composer update amphp/amp
Loading composer repositories with package information
Updating dependencies                                 
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires amphp/amp 3.0.2 (exact version match: 3.0.2 or 3.0.2.0), found amphp/amp[v3.0.2] but these were not loaded, likely because it conflicts with another require.
  Problem 2
    - amphp/parallel v1.4.3 requires amphp/amp ^2 -> found amphp/amp[v2.0.0, ..., v2.6.4] but it conflicts with your root composer.json require (3.0.2).
    - chesslablab/php-chess 1.4.66 requires rubix/ml ^2.4 -> satisfiable by rubix/ml[2.5.1].
    - rubix/ml 2.5.1 requires amphp/parallel ^1.3 -> satisfiable by amphp/parallel[v1.4.3].
    - chesslablab/php-chess is locked to version 1.4.66 and an update of this package was not requested.

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.

This is because rubix/ml is locked to version 2.5.1.

See RubixML/ML#305

[kelunik]

@programarivm Good call, maybe we should add a version constraint to the install command?

[programarivm]

Well I'm not too sure about this one at the moment. These errors shouldn't be too common unless there is a significant difference between versions ^2.6 and ^3.0 I believe.

If there are out there any libraries using previous versions you may want to just add an informative message.

This is the documentation for version 3. Please note that there are significant differences between versions 2 and 3, and you may encounter dependency issues if your codebase is using any Composer package depending on amphp/amp 2. If that is the case, try to specify the newest version on installation. composer require amphp/amp:3.0.2