From 47357f209d662a2bc6ba9d41cd1c925d5ea7dd8d Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Tue, 16 May 2017 18:51:48 +0200 Subject: [PATCH] Add basic cancellation docs --- docs/cancellation/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/cancellation/README.md diff --git a/docs/cancellation/README.md b/docs/cancellation/README.md new file mode 100644 index 00000000..1b1743bb --- /dev/null +++ b/docs/cancellation/README.md @@ -0,0 +1,9 @@ +# Cancellation + +Amp provides primitives to allow the cancellation of operations, namely `CancellationTokenSource` and `CancellationToken`. + +Every operation that supports cancellation accepts an instance of `CancellationToken` as (optional) argument. The operation then subscribes with `CancellationToken::subscribe()` to any cancellation requests that might happen. If the operation consists of any sub-operations that support cancellation, it passes that same `CancellationToken` instance down to these sub-operations. + +The original caller creates a `CancellationToken` by creating an instance of `CancellationTokenSource` and passing `$cancellationTokenSource->getToken()` to the operation. Only the original caller has access to the `CancellationTokenSource` and can cancel the operation using `CancellationTokenSource::cancel()`. + +> **Note:** Cancellations are advisory only and have don't care semantics. A DNS resolver might ignore cancellation requests after the query has been sent as the response has to be processed anyway and can still be cached. An HTTP client might continue a nearly finished HTTP request to reuse the connection, but might abort a chunked encoding response as it cannot know the end.