Add additional documentation

Most of it has been copied over from https://github.com/revoltphp/event-loop.

Author: kelunik

assets/styles/screen.css

@@ -253,6 +253,15 @@ pre::-webkit-scrollbar-thumb:hover {
     color: #666;
 }
 
+.note {
+    margin: 16px 0;
+    padding: 0 16px;
+    background: #fff;
+    border: 2px solid var(--color-highlight);
+    border-radius: 4px;
+    font-size: 85%;
+}
+
 .mt-1 {
     margin-top: 4px !important;
 }

fundamentals.md

@@ -20,27 +20,27 @@ Cooperative multitasking works by telling the scheduler which events we're inter
 The scheduler will invoke a callback once the event happened.
 Revolt supports the following events:
 
- - **Defer**
+ - [**Defer**](/timers)
 
    {:.small-hint .mt-n2 .mb-1}
    The callback is executed in the next iteration of the event loop. If there are defers scheduled, the event loop won't wait between iterations.
- - **Delay**
+ - [**Delay**](/timers)
 
    {:.small-hint .mt-n2 .mb-1} 
    The callback is executed after the specified number of seconds. Fractions of a second may be expressed as floating point numbers.
- - **Repeat**
+ - [**Repeat**](/timers)
 
    {:.small-hint .mt-n2 .mb-1}
    The callback is executed after the specified number of seconds, repeatedly. Fractions of a second may be expressed as floating point numbers.
- - **Stream readable**
+ - [**Stream readable**](/streams)
 
    {:.small-hint .mt-n2 .mb-1}
    The callback is executed when there's data on the stream to be read, or the connection closed.
- - **Stream writable**
+ - [**Stream writable**](/streams)
 
    {:.small-hint .mt-n2 .mb-1}
    The callback is executed when there's enough space in the write buffer to accept new data to be written.
- - **Signal**
+ - [**Signal**](/signals)
 
    {:.small-hint .mt-n2 .mb-1}
    The callback is executed when the process received a specific signal from the OS.
@@ -50,11 +50,13 @@ The scheduler runs a loop that does a few things in each iteration:
 
  - Check for any deferred callbacks
  - Check for actionable timer / stream / signal events
- - Wait until the next timer watcher expires (unless there are `defer` events to be executed)
+ - Wait until the next timer callback expires (unless there are `defer` events to be executed)
 
 The event loop controls the program flow as long as it runs.
 Once we tell the event loop to run it will maintain control until it is suspended, the application errors out, has nothing left to do, or is explicitly stopped.
 
+## Examples
+
 Consider this very simple example:
 
 ```php
@@ -142,4 +144,135 @@ EventLoop::cancel($timeoutId);
 ```
 
 Obviously we could have simply used `fgets(STDIN)` synchronously in this example.
-We're just demonstrating that it's possible to move in and out of the event loop to mix synchronous tasks with non-blocking tasks as needed.
+We're just demonstrating that it's possible to move in and out of the event loop to mix synchronous tasks with non-blocking tasks as needed.
+
+## Events
+
+Event callbacks are registered using the methods on `Revolt\EventLoop` and are invoked using the following standardized parameter order:
+
+| Method                                | Callback Signature                      |
+| ------------------------------------- | --------------------------------------- |
+| [`EventLoop::defer()`](/timers)       | `function(string $callbackId)`          |
+| [`EventLoop::delay()`](/timers)       | `function(string $callbackId)`          |
+| [`EventLoop::repeat()`](/timers)      | `function(string $callbackId)`          |
+| [`EventLoop::onReadable()`](/streams) | `function(string $callbackId, $stream)` |
+| [`EventLoop::onWritable()`](/streams) | `function(string $callbackId, $stream)` |
+| [`EventLoop::onSignal()`](/signals)   | `function(string $callbackId, $signal)` |
+
+### Pausing, Resuming and Canceling Callbacks
+
+All event callbacks, regardless of type, can be temporarily disabled and enabled in addition to being cleared via `EventLoop::cancel()`.
+This allows for advanced capabilities such as disabling the acceptance of new socket clients in server applications when simultaneity limits are reached.
+In general, the performance characteristics of event callback reuse via `enable()`/`disable()` are favorable by comparison to repeatedly canceling and re-registering callbacks.
+
+#### Pausing Callbacks
+
+A simple disable example:
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+// Register a callback we'll disable
+$callbackIdToDisable = EventLoop::delay(1, function (): void {
+    echo "I'll never execute in one second because: disable()\n";
+});
+
+// Register a callback to perform the disable() operation
+EventLoop::delay(0.5, function () use ($callbackIdToDisable) {
+    echo "Disabling callback: ", $callbackIdToDisable, "\n";
+    EventLoop::disable($callbackIdToDisable);
+});
+
+EventLoop::run();
+```
+
+After our second event callback executes the event loop exits because there are no longer any enabled event callbacks registered to process.
+
+#### Resuming Callbacks
+
+`enable()` is the diametric analog of the `disable()` example demonstrated above:
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+// Register a repeating timer callback
+$callbackId = EventLoop::repeat(1, function(): void {
+    echo "tick\n";
+});
+
+// Disable the callback
+EventLoop::disable($callbackId);
+
+EventLoop::defer(function () use ($callbackId): void {
+    // Immediately enable the callback when the event loop starts
+    EventLoop::enable($callbackId);
+    // Now that it's enabled we'll see tick output in our console every second.
+});
+
+EventLoop::run();
+```
+
+#### Cancelling Callbacks
+
+It's important to *always* cancel persistent event callbacks once you're finished with them, or you'll create memory leaks in  your application.
+This functionality works in exactly the same way as the above `enable` / `disable` examples:
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+$callbackId = EventLoop::repeat(1, function (): void {
+    echo "tick\n";
+});
+
+// Cancel $callbackId in five seconds and exit the event loop
+EventLoop::delay(5, function () use ($callbackId): void {
+    EventLoop::cancel($callbackId);
+});
+
+EventLoop::run();
+```
+
+#### Cancellation Safety
+
+It is always safe to cancel a callback from within itself. For example:
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+$increment = 0;
+
+EventLoop::repeat(0.1, function ($callbackId) use (&$increment): void {
+    echo "tick\n";
+    if (++$increment >= 3) {
+        EventLoop::cancel($callbackId); // <-- cancel myself!
+    }
+});
+
+EventLoop::run();
+```
+
+It is also always safe to cancel a callback from multiple places. A double-cancel will simply be ignored.
+
+### Referencing Callbacks
+
+Callbacks can either be referenced or unreferenced. An unreferenced callback doesn't keep the event loop alive.
+All callbacks are referenced by default.
+
+One example to use unreferenced callbacks is when using signal callbacks.
+Generally, if all callbacks are gone and only the signal callback still exists, you want to exit the event loop unless you're not actively waiting for that event to happen.
+
+#### Referencing Callbacks
+
+`reference()` marks a callback as referenced. Takes the `$callbackId` as first and only argument.
+
+#### Unreferencing Callbacks
+
+`unreference()` marks a callback as unreferenced. Takes the `$callbackId` as first and only argument.

layouts/base.html

@@ -58,17 +58,17 @@
                 <a href="/fundamentals">Fundamentals</a>
             </li>
 
-<!--            <li>-->
-<!--                <a href="/#timers">Timers</a>-->
-<!--            </li>-->
+            <li>
+                <a href="/timers">Timers</a>
+            </li>
 
-<!--            <li>-->
-<!--                <a href="/#timers">Streams</a>-->
-<!--            </li>-->
+            <li>
+                <a href="/streams">Streams</a>
+            </li>
 
-<!--            <li>-->
-<!--                <a href="/#timers">Signals</a>-->
-<!--            </li>-->
+            <li>
+                <a href="/signals">Signals</a>
+            </li>
 
 <!--            <li>-->
 <!--                <a href="/#timers">Fibers</a>-->

signals.md

@@ -0,0 +1,40 @@
+---
+title: Signals
+permalink: /signals
+layout: base
+---
+# Signals
+
+Signals are [standardized messages in Unix-like operating systems](https://en.wikipedia.org/wiki/Signal_(IPC)).
+
+## Signal Callbacks
+
+`EventLoop::onSignal()` can be used to react to signals sent to the process.
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+// Let's tick off output once per second, so we can see activity.
+EventLoop::repeat(1, function (): void {
+    echo "tick: ", date('c'), "\n";
+});
+
+// What to do when a SIGINT signal is received
+EventLoop::onSignal(SIGINT, function (): void {
+    echo "Caught SIGINT! exiting ...\n";
+    exit;
+});
+
+EventLoop::run();
+```
+
+As should be clear from the [fundamentals](/fundamentals), signal callbacks may be enabled, disabled and canceled like any other event callback.
+
+Generally, if all callbacks are gone and only the signal callback still exists, you want to exit the event loop unless you're not actively waiting for that event to happen.
+
+### Signal Number Availability
+
+`ext-uv` exposes `UV::SIG*` constants for watchable signals. Applications using the `EventDriver` will need to manually
+specify the [appropriate integer signal numbers](https://en.wikipedia.org/wiki/Signal_(IPC)#Default_action) when registering signal callbacks or rely on `ext-pcntl`.

streams.md

@@ -0,0 +1,101 @@
+---
+title: Streams
+permalink: /streams
+layout: base
+---
+# Streams
+
+Stream callbacks are how we know when we can read and write to sockets and other streams. These events are how we're able
+to actually create things like HTTP servers and asynchronous database libraries using the event loop. As such, stream IO
+callbacks form the backbone of any useful non-blocking, concurrent application.
+
+There are two types of IO callbacks:
+
+- Readability callbacks
+- Writability callbacks
+
+### Readability Callbacks
+
+{:.note}
+> This is an advanced low-level API. Most users should use a stream abstraction instead.
+
+Callbacks registered via `EventLoop::onReadable()` are invoked in the following situations:
+
+- When data is available to read on the stream under observation
+- When the stream is at EOF (for sockets, this means the connection is broken)
+
+A common usage pattern for reacting to readable data looks something like this example:
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+const IO_GRANULARITY = 32768;
+
+function isStreamDead($socket): bool {
+    return !is_resource($socket) || @feof($socket);
+}
+
+EventLoop::onReadable($socket, function ($callbackId, $socket) {
+    $socketId = (int) $socket;
+    $newData = @fread($socket, IO_GRANULARITY);
+    if ($newData != "") {
+        // There was actually data and not an EOF notification. Let's consume it!
+        parseIncrementalData($socketId, $newData);
+    } elseif (isStreamDead($socket)) {
+        EventLoop::cancel($callbackId);
+    }
+});
+
+EventLoop::run();
+```
+
+In the above example we've done a few very simple things:
+
+- Register a readability callback for a socket that will be triggered when there is data available to read.
+- When we read data from the stream in our callback we pass that to a stateful parser that does something
+  domain-specific when certain conditions are met.
+- If the `fread()` call indicates that the socket connection is dead we clean up any resources we've allocated for the
+  storage of this stream. This process should always include calling `EventLoop::cancel()` on any event loop callbacks we
+  registered in relation to the stream.
+
+> You should always read a multiple of the configured chunk size (default: 8192), otherwise your code might not work as expected with loop backends other than `stream_select()`, see [amphp/amp#65](https://github.com/amphp/amp/issues/65) for more information.
+
+### Writabilty Callbacks
+
+{:.note}
+> This is an advanced low-level API. Most users should use a stream abstraction instead.
+
+Callbacks registered via `EventLoop::onWritable()` are invoked in the following situations:
+
+- There's enough free space in the buffer to accept new data to be written.
+- Streams are essentially *"always"* writable. The only time they aren't is when their respective write buffers are
+  full.
+
+A common usage pattern for reacting to writability involves initializing a writability callback without enabling it when
+a client first connects to a server. Once incomplete writes occur we're then able to "unpause" the write callback
+using `EventLoop::enable()` until data is fully sent without having to create and cancel new callbacks on the same
+stream multiple times.
+
+Because streams are essentially *"always"* writable you should only enable writability callbacks while you have data to
+send. If you leave these callbacks enabled when your application doesn't have anything to write the callback will trigger
+endlessly until disabled or canceled. This will max out your CPU. If you're seeing inexplicably high CPU usage in your
+application it's a good bet you've got a writability callback that you failed to disable or cancel after you were
+finished with it.
+
+A standard pattern in this area is to initialize writability callbacks in a disabled state before subsequently enabling
+them at a later time as shown here:
+
+```php
+<?php
+
+use Revolt\EventLoop;
+
+$callbackId = EventLoop::onWritable(STDOUT, function (): void {});
+EventLoop::disable($callbackId);
+// ...
+EventLoop::enable($callbackId);
+// ...
+EventLoop::disable($callbackId);
+```