service
A Typeclass for abstracting over callbacks and futures
A Typeclass for building Async instances, used internally by ClientFactory.
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
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
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.
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.
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
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.
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.
Configuration used to specify a Client's parameters
Configuration used to specify a Client's parameters
The address with which to connect
The request timeout value
The MetricAddress associated with this client
Size of the pending buffer
Size of the sent buffer
When a failure is detected, immediately fail all pending requests.
Retry policy for connections.
How long the connection can remain idle (both sending and receiving data) before it is closed. This should be significantly higher than requestTimeout.
max allowed response size -- larger responses are dropped
Mixed into protocols to provide simple methods for creating clients.
This has to be implemented per codec in order to lift generic Sender traits to a type-specific trait
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]
Thrown when the pending buffer is full
A Codec is a stateful object for converting requests/responses to/from DataBuffers.
A Codec is a stateful object for converting requests/responses to/from DataBuffers. IMPORTANT - when decoding, a codec must be able to handle both partial responses and multiple responses in a single DataBuffer. This is why a codec is stateful and returns a Seq[O]
Provide a Codec as well as some convenience functions for usage within in a Service.
Provide a Codec as well as some convenience functions for usage within in a Service.
the type of codec this provider will supply
Thrown when a request is lost in transit
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. See the docs for
Callback for more information.
Thrown when there's some kind of data error
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
TODO: does this need to actually be a WorkerItem anymore?
A Callback that has been mapped on.
A Callback that has been mapped on. See the docs for Callback for more information
Throw when a request is attempted while not connected
The PermutationGenerator creates permutations such that consecutive calls are guaranteed to cycle though all items as the first element.
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
Returned when a request has been pending for too long
A Sender is anything that is able to asynchronously send a request and receive a corresponding response
A ServiceClient is a non-blocking, synchronous interface that handles sending atomic commands on a connection and parsing their replies
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
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
Configuration class for a Service Server Connection Handler
Configuration class for a Service Server Connection Handler
how long to wait until we timeout the request
how many concurrent requests a single connection can be processing
if true, any uncaught exceptions or service-level errors will be logged
toggle request metrics
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
The ServiceServer provides an interface and basic functionality to create a server that processes requests and returns responses over a codec.
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.
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.
A Callback that has not been mapped.
A Callback that has not been mapped. See the docs for Callback for more information
(Since version 0.8.1) Use FutureClient Instead
A Typeclass for building Async instances, used internally by ClientFactory. This is needed to get the environment into the Async.