Add more worker docs

docs/_config.yml

@@ -24,5 +24,6 @@ defaults:
 shared_asset_path: "/parallel/asset"
 
 navigation:
- - custom-tasks
  - processes
+ - workers
+ - worker-pool

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
+<?php
+
+namespace Amp\Parallel\Worker;
+
+/**
+ * An interface for worker pools.
+ */
+interface Pool extends Worker
+{
+    /** @var int The default maximum pool size. */
+    const DEFAULT_MAX_SIZE = 32;
+
+    /**
+     * Gets a worker from the pool. The worker is marked as busy and will only be reused if the pool runs out of
+     * idle workers. The worker will be automatically marked as idle once no references to the returned worker remain.
+     *
+     * @return \Amp\Parallel\Worker\Worker
+     *
+     * @throws \Amp\Parallel\Context\StatusError If the queue is not running.
+     */
+    public function getWorker(): Worker;
+
+    /**
+     * Gets the number of workers currently running in the pool.
+     *
+     * @return int The number of workers.
+     */
+    public function getWorkerCount(): int;
+
+    /**
+     * Gets the number of workers that are currently idle.
+     *
+     * @return int The number of idle workers.
+     */
+    public function getIdleWorkerCount(): int;
+
+    /**
+     * Gets the maximum number of workers the pool may spawn to handle concurrent tasks.
+     *
+     * @return int The maximum number of workers.
+     */
+    public function getMaxSize(): int;
+}
+```
+
+If a set of tasks should be run within a single worker, use the `Pool::getWorker()` method to pull a single worker from the pool.
+The worker is automatically returned to the pool when the instance returned is destroyed.
+
+### Global worker pool
+
+A global worker pool is available and can be set using the function `Amp\Parallel\Worker\pool(?Pool $pool = null)`.
+Passing an instance of `Pool` will set the global pool to the given instance. Invoking the function without an instance will return
+the current global instance.

docs/workers.md

@@ -1,12 +1,65 @@
 ---
-title: Custom Tasks
+title: Workers
-permalink: /custom-tasks
+permalink: /workers
 ---
-Instead of passing simple callables to workers, this package also allows custom implementations of the `Task` interface to dispatch work in child processes or threads.
+
+## `Worker`
+
+`Worker` provides a simple interface for executing PHP code in parallel in a separate PHP process or thread.
+Classes implementing [`Task`](#task) are used to define the code to be run in parallel.
+
+```php
+<?php
+
+namespace Amp\Parallel\Worker;
+
+use Amp\Promise;
+
+/**
+ * An interface for a parallel worker thread that runs a queue of tasks.
+ */
+interface Worker
+{
+    /**
+     * Checks if the worker is running.
+     *
+     * @return bool True if the worker is running, otherwise false.
+     */
+    public function isRunning(): bool;
+
+    /**
+     * Checks if the worker is currently idle.
+     *
+     * @return bool
+     */
+    public function isIdle(): bool;
+
+    /**
+     * Enqueues a task to be executed by the worker.
+     *
+     * @param Task $task The task to enqueue.
+     *
+     * @return \Amp\Promise<mixed> Resolves with the return value of Task::run().
+     */
+    public function enqueue(Task $task): Promise;
+
+    /**
+     * @return \Amp\Promise<int> 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
 <?php