Merge branch 'release/v3.3.0'

README.md

@@ -17,13 +17,13 @@ task { "world" } and task { "Hello" } success {
 Please refer to the [Kovenant](http://kovenant.komponents.nl) site for API usage and more.
 
 ## Getting started
-Build against Kotlin: `1.0.1-2`.
+Build against Kotlin: `1.0.3`.
 Source and target compatibility is `1.6`
 
 ###Gradle
 ```groovy
 dependencies {
-    compile 'nl.komponents.kovenant:kovenant:3.2.2'
+    compile 'nl.komponents.kovenant:kovenant:3.3.0'
 }
 ```
 
@@ -32,7 +32,7 @@ dependencies {
 <dependency>
 	<groupId>nl.komponents.kovenant</groupId>
 	<artifactId>kovenant</artifactId>
-	<version>3.2.2</version>
+	<version>3.3.0</version>
 </dependency>
 ```
 

build.gradle

@@ -20,7 +20,7 @@
  */
 
 buildscript {
-    ext.kotlinVersion = '1.0.1-2'
+    ext.kotlinVersion = '1.0.3'
     ext.extraConfVersion = '2.2.+'
 
     repositories {
@@ -39,7 +39,7 @@ buildscript {
 
 allprojects {
     ext {
-        appVersion = '3.2.2'
+        appVersion = '3.3.0'
         appGroup = 'nl.komponents.kovenant'
 
 

docs/docs/android/config.md

@@ -10,34 +10,40 @@ a constant creation and destruction of threads. That's not good for responsivene
 
 So we need to keep our threads alive. That also implies we need to tell when to shut them down again. Kovenant
 introduces two convenience functions, `startKovenant()` and `stopKovenant()`, to keep threads alive and shut them 
-down at the proper time again.
+down at the proper time again. This only needs to be done once per application. 
 
-So it all comes down to this:
+So the recommended way to setup (and shutdown) Kovenant is by providing your own [`Application`](http://developer.android.com/reference/android/app/Application.html) implementation:
 
 ```kt
-public class MainActivity : ... {
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        setContentView(...)
-
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
         // Configure Kovenant with standard dispatchers
+        // suitable for an Android environment.
         startKovenant()
-
     }
 
-    ...
-
-    override fun onDestroy() {
-        // Dispose of the Kovenant thread pools
-        // for quicker shutdown you could use
-        // force=true, which ignores all current
+    override fun onTerminate() {
+        super.onTerminate()
+        // Dispose of the Kovenant thread pools.
+        // For quicker shutdown you could use
+        // `force=true`, which ignores all current
         // scheduled tasks
         stopKovenant()
-        super.onDestroy()
     }
 }
 ```
 
+Don't forget to properly setup your application in your `AndroidManifest.xml`:
+
+```xml
+<application
+        android:name=".MyApplication">
+
+        <!--activities etc.-->
+</application>
+```
+
 Note that `stopKovenant(force: Boolean = false)` also has a `force` parameter that defaults to `false`. So by default 
 all the queues are depleted. If you don't want this you can always use `force = true` to immediately shutdown the 
 Dispatchers. `stopKovenant` never blocks though.

docs/docs/android/features.md

@@ -2,6 +2,8 @@
 part of [`kovenant-android`](../index.md#artifacts)
 
 ---
+> Please consult the [configuration section](config.md) for properly setting up Kovenant for Android.
+
 While Kovenant is perfectly usable on Android as-is, there are a couple things that are specific to the platform.
 One is that Android applications can only interact with the interface through the main thread. By default
 Kovenant operates on its own maintained pool of threads and thus can't update the UI.

docs/docs/api/core_config.md

@@ -67,7 +67,7 @@ Let me state upfront that this method is *not threadsafe*.
 ```kt
 buildDispatcher {
     name = "Dispatcher Name"
-    numberOfThreads = 1 
+    concurrentTasks = 1 
     exceptionHandler = ...// (Exception) -> Unit
     errorHandler = ... // (Throwable) -> Unit
     pollStrategy { ... }
@@ -76,8 +76,8 @@ buildDispatcher {
 **name**
 Sets the name of this `Dispatcher`. Is also used as thread names appended by a number
 
-**numberOfThreads**
-The maximum number of threads this `Dispatcher` concurrently keeps alive. Note that the actual
+**concurrentTasks**
+The maximum number of tasks this `Dispatcher` concurrently keeps alive. Note that the actual
 number of threads can be lower and depends on how much work is offered. Also, during the lifetime
 of the `Dispatcher` the number ov threads instantiated can be far greater because threads can 
 also be destroyed.
@@ -104,7 +104,7 @@ can be chained and are executed in order of configuration.
 ```kt
 val dispatcher = buildDispatcher {
     name = "Bob the builder"
-    numberOfThreads = 1
+    concurrentTasks = 1
 
     pollStrategy {                
         yielding(numberOfPolls = 1000)

docs/docs/api/core_usage.md

@@ -45,6 +45,26 @@ fun handlePromise(promise: Promise<String, Exception>) {
 }
 ```
 
+---
+
+##Cancelable Deferred
+By default the promise returned by a `Deferred` is _not_ a [`CancelablePromise`](#cancel). Simply because there is no way 
+to tell the owner of the `Promise` that a cancel has been requested. If we however provide a callback to the `deferred` function
+we are able to cancel. What cancelling means is of course up to the one owning the `Deferred`.
+
+
+```kt
+val deferred = deferred<Int, String> {
+    //callback method to receive notification
+    //when cancel is requested
+    println("I'm cancelled by $it")
+}
+
+//Convenience method for trying to cancel promises
+Kovenant.cancel(deferred.promise, "test method")
+```
+
+
 ---
 
 ##Callbacks

docs/docs/changelog.md

@@ -3,6 +3,18 @@
 Changelog of Kovenant. Complying to [Semantic Versioning](http://semver.org).
 Please refer to [roadmap](roadmap.md) for upcoming releases.
 
+##v3.3.0
+
+**general**
+
+* Update to Kotlin 1.0.3
+* [KOV-80](http://issues.komponents.nl/youtrack/issue/KOV-80) enhance/correct the documentation
+
+**core**
+
+* [KOV-87](http://issues.komponents.nl/youtrack/issue/KOV-87) Cancelable deferred
+
+
 ##v3.2.2
 
 **general**

docs/docs/index.md

@@ -25,13 +25,13 @@ Developed with the following [goals](misc/goals.md) in mind.
 * **Dependency free**: when not counting kotlin std 
 
 ## Getting started
-Build against Kotlin: `1.0.1-2`.
+Build against Kotlin: `1.0.3`.
 Source and target compatibility is `1.6`
 
 ###Gradle
 ```groovy
 dependencies {
-    compile 'nl.komponents.kovenant:kovenant:3.2.2'
+    compile 'nl.komponents.kovenant:kovenant:3.3.0'
 }
 ```
 
@@ -40,7 +40,7 @@ dependencies {
 <dependency>
 	<groupId>nl.komponents.kovenant</groupId>
 	<artifactId>kovenant</artifactId>
-	<version>3.2.2</version>
+	<version>3.3.0</version>
 </dependency>
 ```
 

docs/docs/roadmap.md

@@ -5,7 +5,7 @@ Input is always welcome.
 
 ---
 
-##v3.3.0
+##v3.4.0
 
 **expected**
 

projects/core/src/main/kotlin/context-api.kt

@@ -39,10 +39,14 @@ object Kovenant {
 
     fun <V, E> deferred(context: Context = Kovenant.context): Deferred<V, E> = concrete.deferred(context)
 
+    fun <V, E> deferred(context: Context = Kovenant.context, onCancelled: (E) -> Unit): Deferred<V, E> = concrete.deferred(context, onCancelled)
+
     fun stop(force: Boolean = false, timeOutMs: Long = 0, block: Boolean = true): List<() -> Unit> {
         return context.stop(force, timeOutMs, block)
     }
 
+    fun <E> cancel(promise: Promise<*, E>, error: E): Boolean = promise is CancelablePromise && promise.cancel(error)
+
 }
 
 interface Context {
@@ -82,7 +86,7 @@ interface ReconfigurableContext : MutableContext {
 interface DispatcherContext {
     companion object {
         fun create(dispatcher: Dispatcher,
-                          errorHandler: (Exception) -> Unit): DispatcherContext
+                   errorHandler: (Exception) -> Unit): DispatcherContext
                 = StaticDispatcherContext(dispatcher, errorHandler)
     }
 
@@ -137,7 +141,8 @@ fun Kovenant.testMode(failures: (Throwable) -> Unit = { throw it }) {
         workerContext.errorHandler = failures
 
         multipleCompletion = {
-            first, second -> failures(KovenantException("multiple completion: first = $first, second = $second"))
+            first, second ->
+            failures(KovenantException("multiple completion: first = $first, second = $second"))
         }
     }
 }

projects/core/src/main/kotlin/context-jvm.kt

@@ -67,6 +67,8 @@ class ConcreteKovenant {
 
     fun <V, E>deferred(context: Context = Kovenant.context): Deferred<V, E> = concreteDeferred(context)
 
+    fun <V, E> deferred(context: Context = Kovenant.context, onCancelled: (E) -> Unit): Deferred<V, E> = concreteDeferred(context, onCancelled)
+
     private class ThreadSafeContext() : ReconfigurableContext {
 
         private val multipleCompletionDelegate = ThreadSafeLazyVar<(Any?, Any?) -> Unit> {

projects/core/src/main/kotlin/dispatcher-jvm.kt

@@ -219,7 +219,6 @@ private class NonBlockingDispatcher(val name: String,
             val function = workQueue.poll() ?: return remains
             remains.add(function)
         } while (true)
-        throw IllegalStateException("unreachable")
     }
 
     override fun tryCancel(task: () -> Unit): Boolean {

projects/core/src/main/kotlin/promises-api.kt

@@ -19,6 +19,7 @@
  * THE SOFTWARE.
  */
 @file:JvmName("KovenantApi")
+
 package nl.komponents.kovenant
 
 
@@ -269,6 +270,16 @@ interface Promise<out V, out E> {
 fun <V, E> deferred(context: Context = Kovenant.context): Deferred<V, E> = Kovenant.deferred(context)
 
 
+/**
+ * Creates a new [Deferred] instance with a promise that is a [CancelablePromise]
+ *
+ * @param context the context on which the associated [Promise] operates on
+ * @param onCancelled called when the [Promise] has been cancelled
+ * @return newly created [Deferred]
+ */
+fun <V, E> deferred(context: Context = Kovenant.context, onCancelled: (E) -> Unit): Deferred<V, E> = Kovenant.deferred(context, onCancelled)
+
+
 /**
  * Executes the given task on the work [DispatcherContext] of provided [Context] and returns a [Promise].
  * Any Ecxeption is considered a failure.