core
A BackoffMultiplier is used by a BackoffPolicy determines how the amount of time changes in between retry attempts.
A RetryPolicy used to gradually back-off from retries of an operation.
A RetryPolicy used to gradually back-off from retries of an operation. This class is flexible enough to handle most common retry schemes, such as constantly retrying for a given amount of time or exponentially backing-off.
Retry every 30 seconds for up to 5 minutes
BackoffPolicy(30.seconds, BackoffMultiplier.Constant, maxTime = Some(5.minutes), immediateFirstAttempt = false)
Immediately retry once, then backoff exponentially starting at 100 milliseconds, doubling with every attempt until the interval in between attempts is 5 seconds
BackoffPolicy(100.milliseconds, BackoffMultiplier.Exponential(5.seconds))
The base value to use for backing off. This may be used by the multiplier
The multiplier that will be applied to the baseBackoff
The maximim amount of time to allow for retrying
The maximum number of attempts to make
Whether the first retry attempt should be immediate or use the given backoff and multiplier
Convenience implementation of ConnectionHandler which provides implementations for all of the necessary functions.
Convenience implementation of ConnectionHandler which provides implementations for all of the necessary functions. This allows for a devloper to extend this trait and only provide definitions for the functions they require.
This trait abstracts actions performed on a raw socket channel.
This trait abstracts actions performed on a raw socket channel.
This is essentially the only trait that should differ between live connections and fake connections in testing
ClientConnectionHandler is a trait meant to be used with outgoing connections.
This trait contains all connection-level functions that should be accessable to a top-level user.
This trait contains all connection-level functions that should be accessable to a top-level user. It is primarily used by the Server DSL and subsequently the Service DSL, where we want to give users control over disconnecting/become, but not over lower-level tasks like requesting writes.
This is the base trait for all connection handlers.
This is the base trait for all connection handlers. When attached to a connection by a Delegator, these methods will be called in the worker's thread.
A ConnectionHandler is what directly interfaces with a Connection and is the reactor for all of the Connection events that a Worker captures in its SelectLoop.
A trait encapsulating live information about a connection.
A trait encapsulating live information about a connection. This should only contain read-only fields
Used to control slow start of servers, this will exponentially increase its limit over a period of time until max is reached.
Used to control slow start of servers, this will exponentially increase its limit over a period of time until max is reached. Servers use this to gradually increase the number of allowable open connections during the first few seconds of startup, which can help alleviate thundering herd problems due to JVM warmup.
Initializing a limiter with initial equal to max will essentially disable any slow ramp
Configuration object for connection limiting, used as part of server settings.
Configuration object for connection limiting, used as part of server settings. This does not contain the max value because that is already part of ServerSettings
This class is used to report some basic stats about a Connection.
This class is used to report some basic stats about a Connection. This is used in conjunction with the Metrics library and ConnectionPageRenderer.
The domain of this Connection
The host of this Connection
The id of this Connection
The amount of time this Connection has been open
milliseconds since the last read activity on the connection
milliseconds since the last write activity on the connection
The amount of bytes that this Connection has sent
The amount of bytes that this Connection has received
Represent the connection state.
Represent the connection state. NotConnected, Connected or Connecting.
ConnectionVolumeState indicates whether or not if the Server is operating with a normal workload, which is represented by the current ratio of used / available connections being beneath the ServerSettings.highWatermarkPercentage amount.
ConnectionVolumeState indicates whether or not if the Server is operating with a normal workload, which is represented by the current ratio of used / available connections being beneath the ServerSettings.highWatermarkPercentage amount. Once this ratio is breached, the state will be changed to the HighWater state.
In this state, the server will more aggressively timeout and close idle connections. Effectively what this means is that when the Server polls its connections in the Highwater state, any connection that is seen as idle for longer than ServerSettings.highWaterMaxIdleTime will be reaped. It does this in an effort to free up space.
The Server will return back to its normal state when the connection ratio recedes past the lowWater mark.
Represents the binding of an item to a worker
This is the connection handler on which the controller and service layers are built.
This is the connection handler on which the controller and service layers are built. It contains some common functionality that is ultimately exposed to the users, such as methods to call for disconnecting and safely getting a reference to the ConnectionHandle. While there is no requirement to build handlers on top of this one, it is recommended instead of directly implementing the ConnectionHandler trait
A low-overhead abstraction over a byte array.
A low-overhead abstraction over a byte array. This offers much of the same functionally offered by Akka's ByteString, but without any additional overhead. While this makes DataBlock a bit less powerful and flexible, it also makes it considerably faster.
TODO: This is possibly a contender for using in all places where Array[Byte] is used, but thorough benchmarking is needed. It is also possible that the performance of ByteString has improved in later versions of Akka, so that should also be tested before expanding on this any more.
A thin wrapper around a NIO ByteBuffer with data to read
A thin wrapper around a NIO ByteBuffer with data to read
DataBuffers are the primary way that data is read from and written to a connection. DataBuffers are mutable and not thread safe. They can only be read from once and cannot be reset.
The DataOutBuffer is a ConnectionHandler's interface for writing data out to the connection.
The DataOutBuffer is a ConnectionHandler's interface for writing data out to the connection. DataOutBuffers support a "soft" overflow, which means it will dynamically allocate more space as needed, but is based off a fixed-length base size. The idea is that writing should stop as soon as the overflow is hit, but it is not a requirement.
A DataReader is the result of codec's encode operation.
A DataReader is the result of codec's encode operation. It can either return a DataBuffer, which contains the entire encoded object at once, or it can return a DataStream, which has a Sink for streaming the encoded object.
A Delegator is in charge of creating new ConnectionHandler’s for each new connection.
A Delegator is in charge of creating new ConnectionHandler’s for each new connection. Delegators live inside workers and run as part of the worker’s event loop
Delegators are the liaison between the outside world and your application's connection handling logic.
They can hold state, and pass that state to newly created ConnectionHandlers.
They can receive messages from the outside world, and thus be notified of changes in their environment by way of the handleMessage.
This is triggered by utilizing the ServerRef's delegatorBroadcast function.
Messages representing why a disconnect occurred.
Messages representing why a disconnect occurred. These can be either normal disconnects or error cases
Subset of DisconnectCause which represent errors which resulted in a disconnect.
A ByteBuffer-backed growable buffer.
A ByteBuffer-backed growable buffer. A fixed-size direct buffer is used for most of the time, but overflows are written to a eponentially growing non-direct buffer.
Be aware, the DataBuffer returned from data merely wraps the underlying
buffer to avoid copying
A mixin trait for worker items that defines a method which is periodically called by the worker.
A mixin trait for worker items that defines a method which is periodically called by the worker. This can be used to do periodic checks
An Initializer is used to perform any setup/coordination logic for a
Server! inside a Worker.
An Initializer is used to perform any setup/coordination logic for a
Server! inside a Worker. Initializers are also used to provide new
connections from the server with connection handlers. An initializer is
created per worker, so all actions on a single Initializer are
single-threaded. See colossus.core.Server! to see how Initializer is
used when starting servers.
A Simple mixin trait that will cause the worker to not automatically unbind this handler if the connection it's attached to is closed.
A Simple mixin trait that will cause the worker to not automatically unbind this handler if the connection it's attached to is closed. This mixin is required if a connection handler wants to handle retry logic, since this trait will allow it to continue to receive messages during the reconnection process and bind to another connection
This is a mixin for WorkerItem that gives it actor-like capabilities.
This is a mixin for WorkerItem that gives it actor-like capabilities. A "proxy" Akka actor is spun up, such that any message sent to the proxy will be relayed to the WorkerItem.
The proxy actors lifecycle will be linked to the lifecycle of this
workeritem, so if the actor is kill, the shutdownRequest method will be
invoked, and likewise if this item is unbound the proxy actor will be killed.
A RetryAttempt represents the next action that should be taken when retring an operation.
A RetryIncident is a state machine for managing the retry logic of a single incident of a failed operation.
A RetryIncident is a state machine for managing the retry logic of a single
incident of a failed operation. It is generally unaware of what that
operation is and takes no action itself, but instead is used by the performer
of the operation as a control flow mechanism. For example, when a
colossus.service.ServiceClient fails to connect to its target host, it
will create a new RetryIncident from it's given RetryPolicy.
On each successive failure of the operation, a call to nextAttempt()
should be made that will return a RetryAttempt indicating what action
should be taken. A single RetryIncident cannot be reused should be
discarded when either the operation completes or gives up
A RetryPolicy provides a scheme for managing controlled retries of some operation.
A RetryPolicy provides a scheme for managing controlled retries of some
operation. For example, colossus.service.ServiceClient uses a RetryPolicy to determine
how it should try to reconnect if it's first attempt to connect fails.
RetryPolicy acts as a factory for RetryIncident, which is a per-incident
manager of retries. So everytime a user encounters a sitiation where an
operation needs to be retried, it should use the RetryPolicy create a new
incident, and use the incident until either the operation succeeds or the
incident indicates to stop retrying.
Configuration used to specify a Server's application-level behavior
Configuration used to specify a Server's application-level behavior
As opposed to ServerSettings which contains just lower-level config, ServiceConfig contains higher-level settings. Ideally, abstraction layers on top of the core layer should provide an API that allows users to create a specialized server, where the delegator factory is provided by the API and the name and settings by the user.
Name of the Server, all reported metrics are prefixed using this name
Factory to generate colossus.core.Delegators for each Worker
lower-level server configuration settings
Mixin containing events just for server connection handlers
An instance of this is handed to every new server connection handler
A ServerRef is a handle to a created server.
A ServerRef is a handle to a created server. It can be used to get basic
information about the state of the server as well as send operational
commands to it.
Contains values for configuring how a Server operates
Contains values for configuring how a Server operates
These are all lower-level configuration settings that are for the most part not concerned with a server's application behavior
The low/high watermark percentages are used to help mitigate connection
overload. When a server hits the high watermark percentage of live
connections, it will change the idle timeout from maxIdleTime to
highWaterMaxIdleTime in an attempt to more aggressively close idle
connections. This will continue until the percentage drops below
lowWatermarkPercentage. This can be totally disabled by just setting both
watermarks to 1.
Port on which this Server will accept connections
Max number of simultaneous live connections
Maximum idle time for connections when in non high water conditions
Percentage of live/max connections which represent a normal state
Percentage of live/max connections which represent a high water state.
Max idle time for connections when in high water conditions.
Set the max number of simultaneous connections awaiting accepting, or None for NIO default
A colossus.core.RetryPolicy describing how to retry binding to the port if the first attempt fails. By default it will keep retrying forever.
A colossus.core.WaitPolicy describing how to handle delegator startup. Since a Server waits for a signal from the colossus.IOSystem that every worker has properly initialized a colossus.core.Delegator, this determines how long to wait before the initialization is considered a failure and whether to retry the initialization.
Once a Server begins to shutdown, it will signal a request to every open connection. This determines how long it will wait for every connection to self-terminate before it forcibly closes them and completes the shutdown.
Represents the current state of a Server.
Represents the current state of a Server.
Represents if the a Server's connections are normal or in highwater
Represents the Server's current status
Represents the startup status of the server.
Represents the startup status of the server.
Initializing : The server was just started and is registering with the IOSystemBinding : The server is registered and in the process of binding to its portBound : The server is actively listening on the port and accepting connectionsShuttingDown : The server is shutting down. It is no longer accepting new connections and waiting for existing connections to closeDead : The server is fully shutdown
A WaitPolicy describes configuration for any process that needs to wait for some operation to complete, and if/how to retry the operation if it fails to complete within the waiting time.
A WaitPolicy describes configuration for any process that needs to wait for some operation to complete, and if/how to retry the operation if it fails to complete within the waiting time.
For example, a WaitPolicy is used by colossus.core.Server to determine how long to wait for it's delegators to start up and how to respond if they fail
How long to wait before the operation should be considered timed out
The policy that dictates how to retry the operation if it either fails or times out
A Watched handler allows an actor to be tied to a connection.
A Watched handler allows an actor to be tied to a connection. The worker will watch the actor, and on termination will shutdown the connection associated with the actor
These are a different class of Commands to which a worker will respond.
These are a different class of Commands to which a worker will respond. These are more relevant to the lifecycle of WorkerItems
Contains the configuration for each Worker.
Contains the configuration for each Worker. Created when Workers are spawned by the WorkerManager. Notice - currently the worker config cannot contain the MetricSystem, because workers are created as a part of creating the MetricSystem
The IOSystem to which this Worker belongs
This Worker's unique id amongst its peers.
A WorkerItem is anything that can be bound to worker to receive both events and external messages.
A WorkerItem is anything that can be bound to worker to receive both events and external messages. WorkerItems are expected to be single-threaded and non-blocking. Once a WorkerItem is bound to a worker, all of its methods are executed in the event-loop thread of the bound worker.
Note - WorkerItems currently do not automatically bind to a worker on construction. This is because a worker does the binding itself for server connections immediately on construction. Clients need to bind themselves, except when created through the BindAndCreateWorkerItem message. Maybe this should change.
Note - WorkerItem cannot simply just always generate its own context, since in some cases we want one WorkerItem to replace another, in which case the context must be transferred
This keeps track of all the bound worker items, and properly handles added/removing them
This is a Worker's public interface.
This is a Worker's public interface. This is what can be used to communicate with a Worker, as it wraps the Worker's ActorRef, as well as providing some additional information which can be made public.
This is passed to handlers to give them a way to synchronously write to the connection.
This is passed to handlers to give them a way to synchronously write to the connection. Services wrap this
A RetryPolicy that will never retry
The entry point for starting a Server
Like the server actor, it is critical that instances of this actor get their own thread, since they block when waiting for events.
Like the server actor, it is critical that instances of this actor get their own thread, since they block when waiting for events.
Workers are the "engine" of Colossus. They are the components which receive and operate on Connections, respond to java NIO select loop events and execute the corresponding reactors in the Delegator and ConnectionHandlers.
These are the messages to which a Worker will respond.
A BackoffMultiplier is used by a BackoffPolicy determines how the amount of time changes in between retry attempts. For example, with a BackoffMultiplier.Linear multiplier (with a base backoff of 50 milliseconds), the amount of time in between retries will increase by 50 milliseconds each time.