Merge branch 'release/v3.0.0-beta.3'

README.md

@@ -1,4 +1,7 @@
-[![CircleCI branch](https://img.shields.io/circleci/project/mplatvoet/kovenant/master.svg)](https://circleci.com/gh/mplatvoet/kovenant/tree/master) [![Maven Central](https://img.shields.io/maven-central/v/nl.komponents.kovenant/kovenant.svg)](http://search.maven.org/#browse%7C1069530195) [![DUB](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/mplatvoet/kovenant/blob/master/LICENSE)
+[![CircleCI branch](https://img.shields.io/circleci/project/mplatvoet/kovenant/master.svg)](https://circleci.com/gh/mplatvoet/kovenant/tree/master) [![Maven Central](https://img.shields.io/maven-central/v/nl.komponents.kovenant/kovenant.svg)](http://search.maven.org/#browse%7C1069530195) [![DUB](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/mplatvoet/kovenant/blob/master/LICENSE.txt) 
+develop: [![Develop dependency status](https://www.versioneye.com/user/projects/55b088c23865620018000203/badge.svg?style=flat)](https://www.versioneye.com/user/projects/55b088c23865620018000203)
+master: [![Master dependency status](https://www.versioneye.com/user/projects/55b088d23865620017000296/badge.svg?style=flat)](https://www.versioneye.com/user/projects/55b088d23865620017000296)
+
 
 #Kovenant
 [Promises](http://en.wikipedia.org/wiki/Futures_and_promises) for [Kotlin](http://kotlinlang.org). 
@@ -14,13 +17,17 @@ async { "world" } and async { "Hello" } success {
 Please refer to the [Kovenant](http://kovenant.komponents.nl) site for API usage and more.
 
 ## Getting started
-This version is build against `kotlin-stdlib:1.0.0-beta-1038`.
+Build against Kotlin 1.0 beta 3: `1.0.0-beta-3595`.
 Source and target compatibility is `1.6`
 
+###Snapshot repository
+Snapshot builds can be found at:
+`http://oss.sonatype.org/content/repositories/snapshots`
+
 ###Gradle
 ```groovy
 dependencies {
-    compile 'nl.komponents.kovenant:kovenant:3.0.+'
+    compile 'nl.komponents.kovenant:kovenant:3.0.0-beta.3'
 }
 ```
 
@@ -29,7 +36,7 @@ dependencies {
 <dependency>
 	<groupId>nl.komponents.kovenant</groupId>
 	<artifactId>kovenant</artifactId>
-	<version>[3.0.0,3.1.0)</version>
+	<version>3.0.0-beta.3</version>
 </dependency>
 ```
 

build.gradle

@@ -20,7 +20,7 @@
  */
 
 buildscript {
-    ext.kotlinVersion = '1.0.0-beta-1038'
+    ext.kotlinVersion = '1.0.0-beta-3595'
     ext.extraConfVersion = '2.2.+'
 
     repositories {
@@ -38,7 +38,7 @@ buildscript {
 
 allprojects {
     ext {
-        appVersion = '3.0.0'
+        appVersion = '3.0.0-beta.3'
         appGroup = 'nl.komponents.kovenant'
 
 

docs/docs/api/jvm_usage.md

@@ -6,8 +6,8 @@ part of [`kovenant-jvm`](../index.md#artifacts)
 ##Executors
 
 It's likely that your project already uses threadpools or that you want to leverage the threadpool
-Kovenant uses. Because to many threads just leads to context switching and thus performance degradation.
-Therefor Kovenant provides some facilities for interoperability with Java's Executors. 
+Kovenant uses. Because too many threads just leads to context switching and thus performance degradation.
+Therefore Kovenant provides some facilities for interoperability with Java's Executors. 
 
 * To convert Kovenant's `Dispatcher`s to Java's `Executor` use the extension function `asExecutor()` 
 * To convert Kovenant's `Dispatcher`s to Java's `ExecutorService` use the extension function `asExecutorService()`
@@ -44,12 +44,47 @@ private class FibCallable(private val n: Int) : Callable<Pair<Int, Int>> {
 ---
 
 ##Throttle
+There are case where finer control of the number of parallel tasks is needed, for instance when some specific type of task uses vast amounts of memory. This is what a `Throttle` is for. It allows you to limit the number of parallel task completely independent of any underlying `Dispatcher`. So no matter on what `Context` and thus `Dispatcher` your async tasks run, it's always within bounds. 
 
-There are cases where you want to control the number of parallel tasks in certain parts of your application, but not all.
-For instance when some tasks use up large amounts of memory. This is where a `Throttle` comes in to play. With a 
- `Throttle` you're able to configure how many tasks are allowed to run in parallel. A `Throttle` can be used over 
-multiple existing Dispatchers, so you don't have to worry on which context Promises run.
+You create a `Throttle` instance simply calling its constructor with any positive number indicating the maximum number of concurrent tasks:
 
+```kotlin
+// a Throttle with 2 parallel tasks at max
+val myThrottle = Throttle(2)
+```
+
+Optionally you can provide the `Context` on which new async tasks are run on by default. The can always be overridden per specific task. 
+
+```kotlin
+//configure with myContext
+//the default is Kovenant.context
+val myThrottle = Throttle(2, myContext)
+```
+
+###simple tasks
+The easiest way to use a `Throttle` instance is by using the `task` method. This creates a task similar to the general `async` method that gets scheduled somewhere in the future. The result is, of course, a `Promise`
+
+```kotlin
+myThrottle.task {
+     foo()
+} always {
+    println("done")
+}
+```
+
+###manual registering
+Sometimes you want to throttle a whole chain of promises. So you need to manually register the start and end of the chain. The `registerTask` and `registerDone` gives you that freedom. It's up to you to make sure that every `registerTask` is balanced with a countering `registerDone`. Failing to do so may either result in more than the configured tasks to run parallel or simply a deadlock.
+
+```kotlin
+val promise = myThrottle.registerTask { foo() }
+
+//the rest of the chain
+val lastPromise = promise then { bar() } then { baz() }
+
+myThrottle.registerDone(lastPromise)
+```
+
+###Full Throttle example
 ```kt
 fun main(args: Array<String>) {
     Kovenant.context {
@@ -88,4 +123,4 @@ fun main(args: Array<String>) {
     println("all tasks created")
 }
 ```
-
+

docs/docs/index.md

@@ -1,4 +1,4 @@
-[![CircleCI branch](https://img.shields.io/circleci/project/mplatvoet/kovenant/master.svg)](https://circleci.com/gh/mplatvoet/kovenant/tree/master) [![Maven Central](https://img.shields.io/maven-central/v/nl.komponents.kovenant/kovenant.svg)](http://search.maven.org/#browse%7C1069530195) [![DUB](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/mplatvoet/kovenant/blob/master/LICENSE)
+[![CircleCI branch](https://img.shields.io/circleci/project/mplatvoet/kovenant/master.svg)](https://circleci.com/gh/mplatvoet/kovenant/tree/master) [![Maven Central](https://img.shields.io/maven-central/v/nl.komponents.kovenant/kovenant.svg)](http://search.maven.org/#browse%7C1069530195) [![DUB](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/mplatvoet/kovenant/blob/master/LICENSE.txt)
 
 #Kovenant
 [Promises](http://en.wikipedia.org/wiki/Futures_and_promises) for [Kotlin](http://kotlinlang.org)
@@ -25,13 +25,17 @@ Developed with the following [goals](misc/goals.md) in mind.
 * **Dependency free**: when not counting kotlin std 
 
 ## Getting started
-This version is build against `kotlin-stdlib:1.0.0-beta-1038`.
+Build against Kotlin 1.0 beta 3: `1.0.0-beta-3595`.
 Source and target compatibility is `1.6`
 
+###Snapshot repository
+Snapshot builds can be found at:
+`http://oss.sonatype.org/content/repositories/snapshots`
+
 ###Gradle
 ```groovy
 dependencies {
-    compile 'nl.komponents.kovenant:kovenant:3.0.+'
+    compile 'nl.komponents.kovenant:kovenant:3.0.0-beta.3'
 }
 ```
 
@@ -40,7 +44,7 @@ dependencies {
 <dependency>
 	<groupId>nl.komponents.kovenant</groupId>
 	<artifactId>kovenant</artifactId>
-	<version>[3.0.0,3.1.0)</version>
+	<version>3.0.0-beta.3</version>
 </dependency>
 ```
 

projects/android/src/main/kotlin/configuration.kt

@@ -18,12 +18,13 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
-
+@file:JvmName("KovenantAndroid")
 package nl.komponents.kovenant.android
 
+import android.os.Process
 import nl.komponents.kovenant.Dispatcher
 import nl.komponents.kovenant.Kovenant
-import nl.komponents.kovenant.buildDispatcher
+import nl.komponents.kovenant.buildJvmDispatcher
 import nl.komponents.kovenant.ui.KovenantUi
 import java.util.concurrent.atomic.AtomicInteger
 import java.util.concurrent.atomic.AtomicReference
@@ -38,7 +39,7 @@ public fun startKovenant() {
 }
 
 
-
+@JvmOverloads
 public fun stopKovenant(force: Boolean = false) {
     val dispose = disposable.get()
     if (dispose != null && disposable.compareAndSet(dispose, null)) {
@@ -57,22 +58,26 @@ public fun configureKovenant(): Disposable {
         dispatcher = androidUiDispatcher()
     }
 
-    val callbackDispatcher = buildDispatcher {
+    val callbackDispatcher = buildJvmDispatcher {
         name = "kovenant-callback"
         concurrentTasks = 1
 
         pollStrategy {
             yielding(numberOfPolls = 100)
             blocking()
         }
+
+        threadFactory = createThreadFactory(android.os.Process.THREAD_PRIORITY_BACKGROUND)
     }
-    val workerDispatcher = buildDispatcher {
+    val workerDispatcher = buildJvmDispatcher {
         name = "kovenant-worker"
 
         pollStrategy {
             yielding(numberOfPolls = 100)
             blocking()
         }
+
+        threadFactory = createThreadFactory(android.os.Process.THREAD_PRIORITY_BACKGROUND)
     }
 
     Kovenant.context {
@@ -86,6 +91,15 @@ public fun configureKovenant(): Disposable {
     return DispatchersDisposable(workerDispatcher, callbackDispatcher)
 }
 
+private fun createThreadFactory(priority: Int) : (Runnable, String, Int) -> Thread = {
+    target, dispatcherName, id ->
+    val wrapper = Runnable {
+        Process.setThreadPriority(priority)
+        target.run()
+    }
+    Thread(wrapper, "$dispatcherName-$id")
+}
+
 
 /**
  * Disposes of a resource.

projects/android/src/main/kotlin/dispatcher.kt

@@ -18,6 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
+@file:JvmName("KovenantAndroidDispatcher")
 package nl.komponents.kovenant.android
 
 import android.os.Looper
@@ -34,6 +35,7 @@ public enum class DispatcherType {
 
 public fun androidUiDispatcher(): Dispatcher = BasicAndroidDispatcher.uiDispatcher
 
+@JvmOverloads
 public fun buildLooperDispatcher(looper: Looper,
                                  type: DispatcherType = DispatcherType.BASIC): Dispatcher {
     val executor = LooperExecutor(looper)

projects/android/src/main/kotlin/looper.kt

@@ -18,6 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
+@file:JvmName("KovenantAndroidLooper")
 package nl.komponents.kovenant.android
 
 import android.os.Handler

projects/combine/src/main/kotlin/combine-api.kt

@@ -18,6 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
+@file:JvmName("KovenantCombineApi")
 package nl.komponents.kovenant.combine
 
 import nl.komponents.kovenant.Promise

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

@@ -18,7 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
-
+@file:JvmName("KovenantBulkApi")
 package nl.komponents.kovenant
 
 /**
@@ -38,6 +38,7 @@ package nl.komponents.kovenant
  * @param context the context on which the newly created promise operates on. `Kovenant.context` by default.
  * @param cancelOthersOnError whether an error of one promise attempts to cancel the other (unfinished) promises. `true` by default
  */
+@JvmOverloads
 public fun <V> all(vararg promises: Promise<V, Exception>,
                         context: Context = Kovenant.context,
                         cancelOthersOnError: Boolean = true): Promise<List<V>, Exception> {
@@ -64,6 +65,7 @@ public fun <V> all(vararg promises: Promise<V, Exception>,
  * @param context the context on which the newly created promise operates on. `Kovenant.context` by default.
  * @param cancelOthersOnError whether an error of one promise attempts to cancel the other (unfinished) promises. `true` by default
  */
+@JvmOverloads
 public fun <V> all(promises: List<Promise<V, Exception>>,
                         context: Context = Kovenant.context,
                         cancelOthersOnError: Boolean = true): Promise<List<V>, Exception> {
@@ -90,6 +92,7 @@ public fun <V> all(promises: List<Promise<V, Exception>>,
  * @param context the context on which the newly created promise operates on. `Kovenant.context` by default.
  * @param cancelOthersOnSuccess whether a success of one promise attempts to cancel the other (unfinished) promises. `true` by default
  */
+@JvmOverloads
 public fun <V> any(vararg promises: Promise<V, Exception>,
                         context: Context = Kovenant.context,
                         cancelOthersOnSuccess: Boolean = true): Promise<V, List<Exception>> {
@@ -115,6 +118,7 @@ public fun <V> any(vararg promises: Promise<V, Exception>,
  * @param context the context on which the newly created promise operates on. `Kovenant.context` by default.
  * @param cancelOthersOnSuccess whether a success of one promise attempts to cancel the other (unfinished) promises. `true` by default
  */
+@JvmOverloads
 public fun <V> any(promises: List<Promise<V, Exception>>,
                         context: Context = Kovenant.context,
                         cancelOthersOnSuccess: Boolean = true): Promise<V, List<Exception>> {

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

@@ -18,7 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
-
+@file:JvmName("KovenantContextApi")
 package nl.komponents.kovenant
 
 

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

@@ -19,6 +19,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+@file:JvmName("KovenantDelegatesApi")
 package nl.komponents.kovenant.properties
 
 import nl.komponents.kovenant.Context

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

@@ -18,7 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
-
+@file:JvmName("KovenantDispatcherApi")
 package nl.komponents.kovenant
 
 

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

@@ -18,7 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
-
+@file:JvmName("KovenantExceptionsApi")
 package nl.komponents.kovenant
 
 

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

@@ -18,7 +18,7 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * THE SOFTWARE.
  */
-
+@file:JvmName("KovenantApi")
 package nl.komponents.kovenant
 
 
@@ -224,6 +224,7 @@ public interface Promise<out V, out E> {
      *
      * @return returns the success value when done
      */
+    @Throws(Exception::class)
     public fun get(): V
 
     /**
@@ -234,6 +235,7 @@ public interface Promise<out V, out E> {
      *
      * @return returns the fail value when done
      */
+    @Throws(FailedException::class)
     public fun getError(): E
 
 
@@ -277,6 +279,7 @@ public fun <V, E> deferred(context: Context = Kovenant.context): Deferred<V, E>
  * @param context the context on which the task is executed and the [Promise] is tied to. `Kovenant.context` by default.
  * @return returns a [Promise] of inferred success type [V] and failure type [Exception]
  */
+@JvmOverloads
 public fun <V> async(context: Context = Kovenant.context,
                     body: () -> V): Promise<V, Exception> = concretePromise(context, body)