diff --git a/docs/_config.yml b/docs/_config.yml index ed50509..cbdd980 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -24,5 +24,6 @@ defaults: shared_asset_path: "/parallel/asset" navigation: - - custom-tasks - processes + - workers + - worker-pool diff --git a/docs/worker-pool.md b/docs/worker-pool.md new file mode 100644 index 0000000..1fb7558 --- /dev/null +++ b/docs/worker-pool.md @@ -0,0 +1,67 @@ +--- +title: Worker Pool +permalink: /worker-pool +--- +The easiest way to use workers is through a worker pool. `Pool` implements `Worker`, so worker pools can be used to enqueue +tasks in the same way as a worker, but rather than using a single worker process or thread, the pool uses multiple workers +to execute tasks. This allows multiple tasks to be executed simultaneously. + +## `Pool` + +The `Pool` interface extends [`Worker`](/parallel/workers#worker), adding methods to get information about the pool or pull a single `Worker` instance +out of the pool. A pool uses multiple `Worker` instances to execute enqueued [tasks](/parallel/workers#task). + +```php + Resolves with the return value of Task::run(). + */ + public function enqueue(Task $task): Promise; + + /** + * @return \Amp\Promise Exit code. + */ + public function shutdown(): Promise; + + /** + * Immediately kills the context. + */ + public function kill(); +} +``` ## `Task` The `Task` interface has a single `run()` method that gets invoked in the worker to dispatch the work that needs to be done. +The `run()` method can be written using blocking code since the code is executed in a separate process or thread. The method +may also be asynchronous, returning a `Promise` or `Generator` that is run as a coroutine. ```php