Promise

modules/docs/arrow-docs/docs/_data/menu.yml

@@ -253,6 +253,9 @@ options:
       - title: Effect
         url: /docs/effects/effect/
 
+      - title: Promise
+        url: /docs/effects/promise/
+
       - title: Ref
         url: /docs/effects/ref/
 

modules/docs/arrow-docs/docs/docs/datatypes/intro/README.md

@@ -145,6 +145,10 @@ They are more general than the other datatypes as they combine the abstractions
 
 - [`Observable`]({{ '/docs/integrations/rx2/' | relative_url }})
 
+- [`Promise`]({{ '/docs/effects/promise/' | relative_url }})
+
+- [`Ref`]({{ '/docs/effects/ref/' | relative_url }})
+
 #### Free
 
 [Free]({{ '/docs/patterns/free_algebras/' | relative_url }}) is a general abstraction to represent [Domain Specific Languages]({{ '/docs/patterns/free_algebras/' | relative_url }}) that can be interpreted using Effects.

modules/docs/arrow-docs/docs/docs/effects/promise/README.MD

@@ -0,0 +1,168 @@
+---
+layout: docs
+title: Promise
+permalink: /docs/effects/promise/
+---
+
+## Promise
+
+{:.intermediate}
+intermediate
+
+When made, a `Promise` is empty. Until it is fulfilled, which can only happen once.
+A `Promise` guarantees (promises) `A` at some point in the future within the context of `F`.
+
+## Constructing a Promise
+
+A promise can easily be made by calling `cancellable`.
+Since the allocation of mutable state is not referentially transparent this side-effect is contained within `F`.
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+
+fun main(args: Array<String>) {
+//sampleStart
+val promise: IO<Promise<ForIO, Int>> =
+  Promise.uncancelable<ForIO, Int>(IO.async()).fix()
+//sampleEnd
+println(promise)
+}
+```
+
+In case you want the side-effect to execute immediately and return the `Ref` instance you can use the `unsafe` function.
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+
+fun main(args: Array<String>) {
+//sampleStart
+val unsafePromise: Promise<ForIO, Int> = Promise.unsafeCancellable(IO.async())
+//sampleEnd
+println(unsafePromise)
+}
+```
+
+### Get
+
+Get the promised value, suspending the fiber running the action until the result is available.
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+import arrow.effects.instances.io.monad.flatMap
+
+fun main(args: Array<String>) {
+//sampleStart
+Promise.uncancelable<ForIO, Int>(IO.async()).flatMap { p ->
+  p.get
+} //never ends because `get` keeps waiting for p to be fulfilled.
+//sampleEnd
+}
+```
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+import arrow.effects.instances.io.monad.flatMap
+
+fun main(args: Array<String>) {
+//sampleStart
+val result = Promise.uncancelable<ForIO, Int>(IO.async()).flatMap { p ->
+  p.complete(1).flatMap {
+    p.get
+  }
+}.unsafeRunSync()
+//sampleEnd
+println(result)
+}
+```
+
+### Complete
+
+Fulfills the promise with a value. A promise cannot be fulfilled twice, so doing so results in an error.
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+import arrow.effects.instances.io.monad.flatMap
+
+fun main(args: Array<String>) {
+//sampleStart
+val result = Promise.uncancelable<ForIO, Int>(IO.async()).flatMap { p ->
+  p.complete(2).flatMap {
+    p.get
+  }
+}.unsafeRunSync()
+//sampleEnd
+println(result)
+}
+```
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+import arrow.effects.instances.io.monad.flatMap
+
+fun main(args: Array<String>) {
+//sampleStart
+val result = Promise.uncancelable<ForIO, Int>(IO.async()).flatMap { p ->
+  p.complete(1).flatMap {
+    p.complete(2)
+  }
+}
+  .attempt()
+  .unsafeRunSync()
+//sampleEnd
+println(result)
+}
+```
+
+### Error
+
+Breaks the promise with an exception. A promise cannot be broken twice, so doing so will result in an error.
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+import arrow.effects.instances.io.monad.flatMap
+
+fun main(args: Array<String>) {
+//sampleStart
+val result = Promise.uncancelable<ForIO, Int>(IO.async()).flatMap { p ->
+  p.error(RuntimeException("Break promise"))
+}
+  .attempt()
+  .unsafeRunSync()
+//sampleEnd
+println(result)
+}
+```
+
+{: data-executable='true'}
+```kotlin:ank
+import arrow.effects.*
+import arrow.effects.instances.io.async.async
+import arrow.effects.instances.io.monad.flatMap
+
+fun main(args: Array<String>) {
+//sampleStart
+val result = Promise.uncancelable<ForIO, Int>(IO.async()).flatMap { p ->
+  p.complete(1).flatMap {
+    p.error(RuntimeException("Break promise"))
+  }
+}
+  .attempt()
+  .unsafeRunSync()
+//sampleEnd
+println(result)
+}
+```