Add documentation for TimeLimiter (ReactiveX#152)

* Add documentation for TimeLimiter

* Update timelimiter.adoc

Fix text errors.

Author: maarek

resilience4j-documentation/src/docs/asciidoc/core_guide.adoc

@@ -9,6 +9,7 @@ Core modules:
 * resilience4j-bulkhead: Bulkheading
 * resilience4j-retry: Automatic retrying
 * resilience4j-cache: Response caching
+* resilience4j-timelimiter: Timeout handling
 
 Add-on modules
 
@@ -25,3 +26,4 @@ include::core_guides/ratelimiter.adoc[]
 include::core_guides/bulkhead.adoc[]
 include::core_guides/retry.adoc[]
 include::core_guides/cache.adoc[]
+include::core_guides/timeout.adoc[]

resilience4j-documentation/src/docs/asciidoc/core_guides/timelimiter.adoc

@@ -0,0 +1,61 @@
+=== TimeLimiter
+
+==== Introduction
+
+The TimeLimiter API sets a time limit on the execution of a supplied future. The decorated supplied
+future can be chained with a CircuitBreaker to trip the circuit breaker if the supplied
+future's timeout has exceeded.
+
+The TimeLimiter provides the flexibility to handle custom future implementations such as ones that
+can cancel its execution gracefully. The TimeLimiter by default is configured to cancel the future
+if an exception occurs. This is configurable within the configuration.
+
+==== Examples
+[source,java]
+----
+// For example, you want to restrict the execution of a long running task to 60 seconds.
+TimeLimiterConfig config = TimeLimiterConfig.custom()
+    .timeoutDuration(Duration.ofSeconds(60))
+    .cancelRunningFuture(true)
+    .build();
+
+// Create TimeLimiter
+TimeLimiter timeLimiter = TimeLimiter.of(config);
+----
+
+===== Using a TimeLimiter
+
+TimeLimiter takes a Future Supplier and returns a Callable that will unwrap the Future and attempt
+to retrieve the future's value within the configured timeout period. If the timeout is reached, then
+an exception is thrown upstream and TimeLimiter, if configured, will attempt to cancel the future.
+
+[source,java]
+----
+ExecutorService executorService = Executors.newSingleThreadExecutor();
+
+// Wrap your call to BackendService.doSomething() in a future provided by your executor
+Supplier<Future<Integer>> futureSupplier = () -> executorService.submit(backendService::doSomething)
+
+// Decorate your supplier so that the future can be retrieved and executed upon
+Callable restrictedCall = TimeLimiter
+    .decorateFutureSupplier(timeLimiter, futureSupplier);
+
+Try.of(restrictedCall.call)
+    .onFailure(throwable -> LOG.info("A timeout possibly occurred."));
+----
+
+===== TimeLimiter and CircuitBreaker
+
+The following example shows how to apply a timelimit to a circuit breaker callable.
+
+[source,java]
+----
+Callable restrictedCall = TimeLimiter
+    .decorateFutureSupplier(timeLimiter, futureSupplier);
+
+// Decorate the restricted callable with a CircuitBreaker
+Callable chainedCallable = CircuitBreaker.decorateCallable(circuitBreaker, restrictedCall);
+
+Try.of(chainedCallable::call)
+    .onFailure(throwable -> LOG.info("We might have timed out or the circuit breaker has opened."));
+----

resilience4j-documentation/src/docs/asciidoc/getting_started.adoc

@@ -14,6 +14,7 @@ Core modules:
 * resilience4j-bulkhead: Bulkheading
 * resilience4j-retry: Automatic retrying
 * resilience4j-cache: Response caching
+* resilience4j-timelimiter: Timeout handling
 
 Add-on modules
 
@@ -39,6 +40,7 @@ compile "io.github.resilience4j:resilience4j-ratelimiter:{release-version}"
 compile "io.github.resilience4j:resilience4j-retry:{release-version}"
 compile "io.github.resilience4j:resilience4j-bulkhead:{release-version}"
 compile "io.github.resilience4j:resilience4j-cache:{release-version}"
+compile "io.github.resilience4j:resilience4j-timelimiter:{release-version}"
 ----
 
 ==== Snapshot
@@ -91,6 +93,11 @@ repositories {
     <artifactId>resilience4j-cache</artifactId>
     <version>{release-version}</version>
 </dependency>
+<dependency>
+    <groupId>io.github.resilience4j</groupId>
+    <artifactId>resilience4j-timelimiter</artifactId>
+    <version>{release-version}</version>
+</dependency>
 ----
 
 ==== Snapshot

resilience4j-documentation/src/docs/asciidoc/introduction.adoc

@@ -12,6 +12,7 @@ Core modules:
 * resilience4j-bulkhead: Bulkheading
 * resilience4j-retry: Automatic retrying (sync and async)
 * resilience4j-cache: Response caching
+* resilience4j-timelimiter: Timeout handling
 
 Add-on modules