trait Async [M[_]] extends AnyRef

A Typeclass for abstracting over callbacks and futures

trait AsyncBuilder [M[_], E] extends AnyRef

A Typeclass for building Async instances, used internally by ClientFactory.

A Typeclass for building Async instances, used internally by ClientFactory. This is needed to get the environment into the Async.

class AsyncHandlerGenerator [P <: Protocol] extends AnyRef

So we need to take a type-parameterized request object, package it into a monomorphic case class to send to the worker, and have the handler that receives that object able to pattern match out the parameterized object, all without using reflection.

So we need to take a type-parameterized request object, package it into a monomorphic case class to send to the worker, and have the handler that receives that object able to pattern match out the parameterized object, all without using reflection. We can do that with some nifty path-dependant types

class BasicLiftedClient [P <: Protocol, M[_]] extends LiftedClient[P, M]

trait BasicServiceDSL [P <: Protocol] extends AnyRef

A one stop shop for a fully working Server DSL without any custom functionality.

A one stop shop for a fully working Server DSL without any custom functionality. Just provide a codec and you're good to go

sealed trait Callback [+O] extends AnyRef

A Callback is a Monad for doing in-thread non-blocking operations.

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.

class CallbackExecutionException extends Exception

This exception is only thrown when there's a uncaught exception in the execution block of a Callback.

This exception is only thrown when there's a uncaught exception in the execution block of a Callback. For example,

val c: Callback[Foo] = getCallback()
c.execute{
  case Success(foo) => throw new Exception("exception")
}

will result in a CallbackExecutionException being thrown, however

c.map{_ => throw new Exception("exception")}.execute()

will not because the exception can still be recovered

case class CallbackExecutor (context: ExecutionContext, executor: ActorRef) extends Product with Serializable

A CallbackExecutor represents a scheduler and execution environment for Callbacks and is required when either converting a Future to a Callback or scheduling delayed execution of a Callback.

A CallbackExecutor represents a scheduler and execution environment for Callbacks and is required when either converting a Future to a Callback or scheduling delayed execution of a Callback. Every Worker provides an CallbackExecutor that can be imported when doing such operations.

class CallbackPromise [T] extends AnyRef

A CallbackPromise creates a callback which can be eventually filled in with a value.

A CallbackPromise creates a callback which can be eventually filled in with a value. This works similarly to a scala Promise. CallbackPromises are not thread-safe. For thread-safety, simply use a scala Promise and use Callback.fromFuture on it's corresponding Future.

trait Client [P <: Protocol, M[_]] extends Sender[P, M]

case class ClientConfig (address: Seq[InetSocketAddress], requestTimeout: Duration, name: MetricAddress, pendingBufferSize: Int = 500, sentBufferSize: Int = 100, failFast: Boolean = false, connectRetry: RetryPolicy = ..., idleTimeout: Duration = Duration.Inf, maxResponseSize: DataSize = 1.MB, requestRetry: RetryPolicy = ...) extends Product with Serializable

Configuration used to specify a Client's parameters

address: The address with which to connect
requestTimeout: The request timeout value
name: The MetricAddress associated with this client
pendingBufferSize: Size of the pending buffer
sentBufferSize: Size of the sent buffer
failFast: When a failure is detected, immediately fail all pending requests.
connectRetry: Retry policy for connections.
idleTimeout: How long the connection can remain idle (both sending and receiving data) before it is closed. This should be significantly higher than requestTimeout.
maxResponseSize: max allowed response size -- larger responses are dropped

abstract class ClientFactories [P <: Protocol, T[M[_]] <: Sender[P, M[_]]] extends AnyRef

Mixed into protocols to provide simple methods for creating clients.

trait ClientFactory [P <: Protocol, M[_], +T <: Sender[P, M], E] extends AnyRef

A generic trait for creating clients.

A generic trait for creating clients. There are several more specialized subtypes that make more sense of the type parameters, so this trait should generally not be used unless writing very generic code.

Type Parameters: * P - the protocol used by the client * M[_] - the concurrency wrapper, either Callback or Future * T - the type of the returned client * E - an implicitly required environment type, WorkerRef for Callback and IOSystem for Future

trait ClientLifter [P <: Protocol, T[M[_]] <: Sender[P, M[_]]] extends AnyRef

This has to be implemented per codec in order to lift generic Sender traits to a type-specific trait

For example this is how we go from ServiceClient[HttpRequest, HttpResponse] to HttpClient[Callback]

class ClientOverloadedException extends ServiceClientException

Thrown when the pending buffer is full

sealed trait ClientState extends AnyRef

class CodecClientFactory [P <: Protocol, M[_], T[M[_]] <: Sender[P, M[_]], E] extends ClientFactory[P, M, T[M], E]

class ConfigurableRequestFormatter [I] extends RequestFormatter[I]

The ErrorConfig here is normally loaded from the ServiceConfig.

class ConnectionLostException extends ServiceClientException

Thrown when a request is lost in transit

case class ConstantCallback [O](value: Try[O]) extends Callback[O] with Product with Serializable

A Callback containing a constant value, usually created as the result of calling Callback.success or Callback.failure.

A Callback containing a constant value, usually created as the result of calling Callback.success or Callback.failure. A constant callback is slightly faster than an unmapped callback, but only by a small margin. See the docs for Callback for more information.

class DataException extends ServiceClientException

Thrown when there's some kind of data error

class DefaultTagDecorator [P <: Protocol] extends TagDecorator[P]

class DroppedReplyException extends ServiceServerException

case class ErrorConfig (doNotLog: Set[String], logOnlyName: Set[String]) extends Product with Serializable

class FatalServiceServerException extends ServiceServerException

abstract class Filter [P <: Protocol] extends AnyRef

class FutureAsync extends Async[Future]

trait FutureClient [P <: Protocol] extends Client[P, Future]

class FutureClientFactory [P <: Protocol] extends ClientFactory[P, Future, FutureClient[P], IOSystem]

abstract class GenRequestHandler [P <: Protocol] extends DownstreamEvents with HandlerTail with UpstreamEventHandler[ServiceUpstream[P]]

abstract class HandlerGenerator [T] extends AnyRef

abstract class Interceptor [P <: Protocol] extends AnyRef

case class IrrecoverableError [C](reason: Throwable) extends ProcessingFailure[C] with Product with Serializable

trait LiftedClient [P <: Protocol, M[_]] extends Sender[P, M]

class LoadBalancingClientException extends Exception

case class MappedCallback [I, O](trigger: ((Try[I]) ⇒ Unit) ⇒ Unit, handler: (Try[I]) ⇒ Try[O]) extends Callback[O] with Product with Serializable

A mapped callback is the most generalized implementation of a callback and is usually created when a callback has been mapped on (i.e.

A mapped callback is the most generalized implementation of a callback and is usually created when a callback has been mapped on (i.e. map/mapTry/recover). An unmapped callback and constant callback are specialized versions, that exist to improve performance. For example:

MappedCallback[Int, Int](_ => Success(5), identity[Try[Int]]) <==> ConstantCallback[Int](Success(5))

See the docs for Callback for more information.

class NotConnectedException extends ServiceClientException

Throw when a request is attempted while not connected

trait PermutationGenerator [T] extends AnyRef

class PrinciplePermutationGenerator [T] extends PermutationGenerator[T] with Iterator[List[T]]

The PermutationGenerator creates permutations such that consecutive calls are guaranteed to cycle though all items as the first element.

This currently doesn't iterate through every possible permutation, but it does evenly distribute 1st and 2nd tries...needs some more work

sealed trait ProcessingFailure [C] extends AnyRef

class PromiseException extends Exception

trait Protocol extends AnyRef

class ProxyWatchdog extends Actor

class ReceiveException extends Exception

case class RecoverableError [C](request: C, reason: Throwable) extends ProcessingFailure[C] with Product with Serializable

class RequestBufferFullException extends ServiceServerException

trait RequestFormatter [I] extends AnyRef

class RequestHandlerException extends Exception

class RequestTimeoutException extends ServiceClientException

Returned when a request has been pending for too long

class SendFailedException extends Exception

trait Sender [P <: Protocol, M[_]] extends AnyRef

A Sender is anything that is able to asynchronously send a request and receive a corresponding response

class ServiceClient [P <: Protocol] extends ControllerDownstream[controller.Encoding.Client[P]] with Client[P, Callback] with HandlerTail with ColossusLogging

A ServiceClient is a non-blocking, synchronous interface that handles sending atomic commands on a connection and parsing their replies

Notice - The client will not begin to connect until it is bound to a worker, so when using the default constructor a service client will not connect on it's own. You must either call bind on the client or use the constructor that accepts a worker

TODO: make underlying output controller data size configurable

class ServiceClientException extends Exception

trait ServiceClientFactory [P <: Protocol] extends ClientFactory[P, Callback, Client[P, Callback], WorkerRef]

class ServiceClientPool [T <: Sender[_, Callback]] extends AnyRef

A ClientPool is a simple container of open connections.

A ClientPool is a simple container of open connections. It can receive updates and will open/close connections accordingly.

note that config will be copied for each client, replacing only the address

case class ServiceConfig (requestTimeout: Duration, requestBufferSize: Int, logErrors: Boolean, requestMetrics: Boolean, maxRequestSize: DataSize, errorConfig: ErrorConfig) extends Product with Serializable

Configuration class for a Service Server Connection Handler

requestTimeout: how long to wait until we timeout the request
requestBufferSize: how many concurrent requests a single connection can be processing
logErrors: if true, any uncaught exceptions or service-level errors will be logged
requestMetrics: toggle request metrics
maxRequestSize: max size allowed for requests TODO: remove name from config, this should be the same as a server's name and pulled from the ServerRef, though this requires giving the ServiceServer access to the ServerRef

class ServiceConfigException extends Exception

trait ServiceDSL [T, I <: ServiceInitializer[T]] extends AnyRef

trait ServiceInitializer [T] extends HandlerGenerator[T]

class ServiceServer [P <: Protocol] extends ControllerDownstream[Server[P]] with ServiceUpstream[P] with UpstreamEventHandler[ControllerUpstream[Server[P]]] with DownstreamEventHandler[GenRequestHandler[P]] with ColossusLogging

The ServiceServer provides an interface and basic functionality to create a server that processes requests and returns responses over a codec.

A Codec is simply the format in which the data is represented. Http, Redis protocol, Memcached protocl are all examples(and natively supported). It is entirely possible to use an additional Codec by creating a Codec to parse the desired protocol.

Requests can be processed synchronously or asynchronously. The server will ensure that all responses are written back in the order that they are received.

class ServiceServerException extends Exception

trait ServiceUpstream [P <: Protocol] extends UpstreamEvents

class StaleClientException extends Exception

This is thrown when a Client is manually disconnected, and subsequent attempt is made to reconnect.

This is thrown when a Client is manually disconnected, and subsequent attempt is made to reconnect. To simplify the internal workings of Clients, instead of trying to reset its internal state, it throws. Create a new Client to reestablish a connection.

trait TagDecorator [P <: Protocol] extends AnyRef

class UnbindHandler extends PipelineHandler with ManualUnbindHandler

class UnhandledRequestException extends Exception

case class UnmappedCallback [I](trigger: ((Try[I]) ⇒ Unit) ⇒ Unit) extends Callback[I] with Product with Serializable

A Callback that has not been mapped (i.e.

A Callback that has not been mapped (i.e. map/mapTry/recover). Unmapped callback is the same as a mapped callback that uses the identity function as the handler:

UnmappedCallback[I](func) <==> MappedCallback[I, I](func, identity[Try[I]])

An unmapped callback is 30% faster to execute than the mapped version. See the docs for Callback for more information.

class LoadBalancingClient [P <: Protocol] extends WorkerItem with Sender[P, Callback]

The LoadBalancingClient will evenly distribute requests across a set of clients.

The LoadBalancingClient will evenly distribute requests across a set of clients. If one client begins failing, the balancer will retry up to numRetries times across the other clients (with each failover hitting different clients to avoid a cascading pileup

Note that the balancer will never try the same client twice for a request, so setting maxTries to a very large number will mean that every client will be tried once

Annotations: @deprecated
Deprecated: (Since version 0.11.0) Load balancer now built into client

Packages

service

package service

Type Members

Using Callbacks in Services

Using Callbacks elsewhere

Value Members

Ungrouped

Packages

service 

package service

Type Members

Using Callbacks in Services

Using Callbacks elsewhere

Value Members

Ungrouped

service