colossus.service

Callback

sealed trait Callback[+O] extends AnyRef

A Callback is a Monad for doing in-thread non-blocking operations. It is essentially a "function builder" that uses function composition to chain together a callback function that is eventually passed to another function.

Normally if you have a function that requires a callback, the function looks something like:

def doSomething(param, param, callBack: result => Unit)

and then you'd call it like 

doSomething(arg1, arg2, result => println("got the result"))

This is the well-known continuation pattern, and it something we'd like to avoid due to the common occurrance of deeply nested "callback hell". Instead, the Callback allows us to define out function as

def doSomething(param1, param2): Callback[Result]

and call it like 

val c = doSomething(arg1, arg2)
c.map{ result =>
  println("got the result")
}.execute()

Thus, in practice working with Callbacks is very similar to working with Futures. The big differences from a future are:

1. Callbacks are not thread safe at all. They are entirely intended to stay inside a single worker. Otherwise just use Futures.

2. The execute() method needs to be called once the callback has been fully built, which unlike futures requires some part of the code to know when a callback is ready to be invoked

Using Callbacks in Services

When building services, particularly when working with service clients, you will usually be getting Callbacks back from clients when requests are sent. *Do not call execute yourself!* on these Callbacks. They must be returned as part of request processing, and Colossus will invoke the callback itself.

Using Callbacks elsewhere

If you are using Callbacks in some custom situation outside of services, be aware that exceptions thrown inside a map or flatMap are properly caught and can be recovered using recover and recoverWith, however exceptions thrown in the "final" handler passed to execute are not caught. This is because the final block cannot be mapped on (since it is only passed when the callback is executed) and throwing the exception is preferrable to suppressing it.

Any exception that is thrown in this block is however rethrown as a CallbackExecutionException. Therefore, any "trigger" function you wrap inside a callback should properly catch this exception.

Linear Supertypes
AnyRef, Any
Known Subclasses
ConstantCallback, MappedCallback, UnmappedCallback
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. Callback
  2. AnyRef
  3. Any
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def execute(onComplete: (Try[O]) ⇒ Unit = _ => ()): Unit

  2. abstract def flatMap[U](f: (O) ⇒ Callback[U]): Callback[U]

  3. abstract def map[U](f: (O) ⇒ U): Callback[U]

  4. abstract def mapTry[U](f: (Try[O]) ⇒ Try[U]): Callback[U]

  5. abstract def recover[U >: O](p: PartialFunction[Throwable, U]): Callback[U]

  6. abstract def recoverWith[U >: O](p: PartialFunction[Throwable, Callback[U]]): Callback[U]

Concrete Value Members

  1. final def !=(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  2. final def !=(arg0: Any): Boolean

    Definition Classes
    Any

  3. final def ##(): Int

    Definition Classes
    AnyRef → Any

  4. final def ==(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  5. final def ==(arg0: Any): Boolean

    Definition Classes
    Any

  6. final def asInstanceOf[T0]: T0

    Definition Classes
    Any

  7. def clone(): AnyRef

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  8. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  9. def equals(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  10. def finalize(): Unit

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )

  11. final def getClass(): Class[_]

    Definition Classes
    AnyRef → Any

  12. def hashCode(): Int

    Definition Classes
    AnyRef → Any

  13. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any

  14. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  15. final def notify(): Unit

    Definition Classes
    AnyRef

  16. final def notifyAll(): Unit

    Definition Classes
    AnyRef

  17. final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
    AnyRef

  18. def toFuture(implicit ex: ExecutionContext): Future[O]

    Hook a future into the callback and execute the caller.

    Hook a future into the callback and execute the caller. Use this if you need to hand a callback to something out-of-thread

  19. def toString(): String

    Definition Classes
    AnyRef → Any

  20. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  21. final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  22. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  23. final def withFilter(f: (O) ⇒ Boolean): Callback[O]

  24. def zip[B, C](b: Callback[B], c: Callback[C]): Callback[(O, B, C)]

  25. def zip[B](b: Callback[B]): Callback[(O, B)]

Inherited from AnyRef

Inherited from Any

Ungrouped