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
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 is implemented by colossus.core.PipelineHandler and contains all the methods made available to all layers extending the core layer
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.
Represents the binding of an item to a worker
These are the methods that the downstream neighbor of the CoreHandler must implement
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
These are the methods the Core layer directly exposes to its downstream neighbor which are generally not meant to be exposed further downstream
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.
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.
This trait can be used for layers that are in the head or middle of a pipeline.
This trait can be used for layers that are in the head or middle of a pipeline. It will automatically propagate events to the downstream neighbor. Notice that for each event, the onEvent method is called before propagating the event downstream.
These are events that propagate to each layer starting from the head and moving downstream
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
This trait must be implemented by the last stage of a pipeline
This must be implemented by any non-tail member of a pipeline
This trait must be implemented by any non-head member of a pipeline.
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 instance of this is handed to every new initializer for a server
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
The PipelineHandler forms the foundation of all pipeline-based connection
handlers.
The PipelineHandler forms the foundation of all pipeline-based connection
handlers. It takes the head and tail of a pipeline and properly directs
events to it.
This is a mixin for WorkerItemEvents that gives it actor-like capabilities.
This is a mixin for WorkerItemEvents 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 the bound WorkerItem.
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.
This is intended to be mixed in both to worker items as well as Pipeline Componenents.
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.
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.Initializer, 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.
An UpstreamEventHandler is generally implemented by members of a pipline
that are neither the head nor tail.
An UpstreamEventHandler is generally implemented by members of a pipline
that are neither the head nor tail. This trait will ensure that events are
propagated to upstream neighbors
These are events that propagate starting from the tail and move upstream
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 trait contains event handler methods for when a worker item is bound and unbound to/from a worker.
This trait contains event handler methods for when a worker item is bound and unbound to/from a worker. This is used both by WorkerItem itself as well as components of connection handler pipelines like DownstreamEvents.
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
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.