Abstract Closable
class for Java compatibility.
A Java-friendly API for the ClosableOnce trait.
Abstract Event
class for Java compatibility.
An API for creating Monitor instances in Java.
Abstract Var
class for Java compatibility.
Abstract Witness
class for Java compatibility.
Activity, like Var, is a value that varies over time; but, richer than Var, these values have error and pending states.
Wait for the result of some action.
Wait for the result of some action. Awaitable is not used
directly, but through the Await
object.
Provides an interface for working with a batched com.twitter.util.Future
A "stack" with a bounded size.
A "stack" with a bounded size. If you push a new element on the top when the stack is full, the oldest element gets dropped off the bottom.
Defines a trait that makes the underlying object *cancellable*.
Defines a trait that makes the underlying object *cancellable*. Cancellable objects may be linked to each other (one way) in order to propagate cancellation.
Note that the underlying object may or may not _respond_ to the cancellation request. That is, calling 'cancel()' does not guarantee the cancellation of the computation; rather it is a hint that the provider of the computation may choose to ignore.
Closable is a mixin trait to describe a closable
.resource
Closable is a mixin trait to describe a closable
.resource
Note: There is a Java-friendly API for this trait: com.twitter.util.AbstractClosable.
A mixin trait to describe resources that are an idempotent Closable.
A mixin trait to describe resources that are an idempotent Closable.
The first call to close(Time)
triggers closing the resource with the
provided deadline while subsequent calls will yield the same Future
as the first invocation irrespective of the deadline provided.
A mixin to make an com.twitter.util.Awaitable out of a com.twitter.util.Closable.
A mixin to make an com.twitter.util.Awaitable out of a com.twitter.util.Closable.
Use closeAwaitably
in the definition of close
:
class MyClosable extends Closable with CloseAwaitably { def close(deadline: Time) = closeAwaitably { // close the resource } }
Note: There is a Java-friendly API for this trait: com.twitter.util.AbstractCloseAwaitably
.
A base trait for all Codecs that translate a type T into a serialized form S
A Future
that is already completed.
A Future
that is already completed.
These are cheap in construction compared to Promises
.
Java interface to Credentials.
A base trait for decoders for type T from a serialized form S
A Diff stores the necessary instructions required to bring two version of a data structure into agreement.
A type class that tells how to compute a Diff between
two versions of a collection CC[T]
.
com.twitter.util.Disposable represents a live resource that must be disposed after use.
com.twitter.util.Disposable represents a live resource that must be disposed after use. com.twitter.util.Managed is a factory for creating and composing such resources. Managed resources are composed together so their lifetimes are synchronized.
The following example shows how to build and use composite managed resources:
// Create managed Tracer def mkManagedTracer() = new Managed[Tracer] { def make() = new Disposable[Tracer] { val underlying = new Tracer() def get = underlying def dispose(deadline: Time) = underlying.close() // assumes Tracer uses relese() to manage lifetime } } // Create managed Server using Tracer as dependency def mkManagedServer(t: Tracer) = new Managed[Server] { def make() = new Disposable[Server] { val underlying = new Server(t) // Server requires tracer to be created def get = underlying def dispose(deadline: Time) = underlying.close() // assumes Server uses close() to manage lifetime } } // Create composite resource val compRes: Managed[Server] = for { a <- mkManagedTracer() b <- mkManagedServer(a) } yield b // Use composite resource in safe fashion. It's guaranteed that both resources // will be properly closed/released when done using them. compRes foreach { b => // use b (which is type Server in this case) } // dispose called on both resources
com.twitter.util.Disposable: get can be called multiple times and should return same instance; dispose can be called only once and should release resource that get is returning; calling get after dispose is undefined.
com.twitter.util.Managed: multiple calls to make could return a) new instance or b) ref counted instance of the underlying resource or c) same instance when resource doesn't need to be actually disposed, etc.
Disposable is a container for a resource that must be explicitly disposed when no longer needed. After this, the resource is no longer available.
A Duration
represents the span between two points in time.
A Duration
represents the span between two points in time. It represents
this with a signed long, and thus the largest representable duration is:
106751.days+23.hours+47.minutes+16.seconds +854.milliseconds+775.microseconds+807.nanoseconds
Durations may be constructed via its companion object,
Duration.fromNanoseconds
, Duration.fromSeconds
, etc. or by
using the time conversions:
import com.twitter.conversions.DurationOps._ 3.days+4.nanoseconds
In addition to the timespans in the range of Long.MinValue
to
Long.MaxValue
nanoseconds, durations have two distinguished
values: Duration.Top
and Duration.Bottom
. These have special
semantics: Top
is greater than every other duration, save for
itself; Bottom
is smaller than any duration except for
itself — they act like positive and negative infinity, and
their arithmetic follows. This is useful for representing durations
that are truly infinite; for example the absence of a timeout.
A base trait for encoders of type T into a serialized form S
Events are emitters of values.
Events are emitters of values. They can be processed as if they were streams. Here's how to create one that emits Ints.
val ints = Event[Int]()
To listen to an Event stream for values, register a handler.
val you = ints.respond { n => println(s"$n for you") }
Handlers in Event-speak are called Witnesses.
And, respond is equivalent to register(Witness { ... })
, so we can also
write:
val me = ints.register(Witness { n => println(s"$n for me") })
Registration is time-sensitive. Witnesses registered to an Event stream can't observe past values. In this way, Events are instantaneous. When the stream emits a value, it fans out to every Witness; if there are no Witnesses to that communication, whatever value it carried is lost.
Events emit values, okay, but who decides what is emitted? The implementor of an Event decides!
But there's another way: you can create an Event that is also a Witness.
Remember, Witnesses are simply handlers that can receive a value. Their type
is T => Unit
. So an Event that you can send values to is also a Witness.
The ints
Event we created above is one of these. Watch:
scala> ints.notify(1) 1 for you 1 for me
We can also stop listening. This is important for resource cleanup.
scala> me.close() scala> ints.notify(2) 2 for you
In relation to Vars, Events are instantaneous values, defined only at particular instants in time; whereas Vars are defined at all times. It is possible to view Events as the discrete counterpart to Var's continuous nature.
Note: There is a Java-friendly API for this trait: com.twitter.util.AbstractEvent.
A FuturePool implementation backed by an java.util.concurrent.ExecutorService
.
A FuturePool implementation backed by an java.util.concurrent.ExecutorService
.
If a piece of work has started, it cannot be cancelled and will not propagate
cancellation unless interruptible
is true. If you want to propagate cancellation,
use an InterruptibleExecutorServiceFuturePool.
This class is for Java friendliness.
This class is for Java friendliness. Any Scala method that takes Function1[A, B] can now take a Function[A, B]. Because Function1 is a trait, it is very difficult to instantiate directly in Java.
Represents an asynchronous value.
Represents an asynchronous value.
See the user guide
on concurrent programming with Futures
to better understand how they
work and can be used.
A Future[T]
can be in one of three states:
T
(a Return)Throwable
result (a Throw)This definition of Future
does not assume any concrete implementation;
in particular, it does not couple the user to a specific executor or event loop.
Futures for Java-friendly APIs.
The user guide on concurrent programming with Futures.
A Java friendly API for handling side-effects for a Future
.
A Java friendly API for handling side-effects for a Future
.
If you want a Java API to sequence the work you can use a FutureTransformer.
FutureTransformer for a Java API for transforming the results of Futures.
Future.addEventListener for using it with a Future
.
Future.respond which is the equivalent Scala API for further details.
A FuturePool
executes tasks asynchronously, typically using a pool
of worker threads.
An alternative interface for performing Future transformations; that is, converting a Future[A] to a Future[B].
An alternative interface for performing Future transformations;
that is, converting a Future[A] to a Future[B]. This interface is
designed to be friendly to Java users since it does not require
creating many small Function objects. It is used in conjunction
with transformedBy
.
You must override one of {map, flatMap}
. If you override both
map
and flatMap
, flatMap
takes precedence. If you fail to
override one of {map, flatMap}
, an AbstractMethodError
will be
thrown at Runtime.
Note: to end a result with a failure, we encourage you to use either
flatMap
or rescue
and return a failed Future, instead of throwing an
exception. A failed future can be used by returning
Future.exception(throwable)
instead of throwing an exception.
FutureEventListener for a Java API for side-effects.
Future.transformedBy for using it with a Future
.
Future.transform which is the equivalent Scala API for further details.
A FuturePool backed by a java.util.concurrent.ExecutorService
that supports cancellation.
A mixin to allow scala objects to be used from java.
A Timer that is implemented via a java.util.Timer.
A Timer that is implemented via a java.util.Timer.
This timer has millisecond granularity.
If your code has a reasonably high throughput of task scheduling and can trade off some precision of when tasks run, Finagle has a higher throughput hashed-wheel implementation.
Due to the implementation using a single Thread
, be wary of
scheduling tasks that take a long time to execute (e.g. blocking IO)
as this blocks other tasks from running at their scheduled time.
An implementation of java.util.Queue that has LIFO order and a maximum capacity of 1 When the Queue is full, a push replaces the item.
A Local is a ThreadLocal whose scope is flexible.
A Local is a ThreadLocal whose scope is flexible. The state of all Locals may be saved or restored onto the current thread by the user. This is useful for threading Locals through execution contexts.
Promises pass locals through control dependencies, not through data
dependencies. This means that Locals have exactly the same semantics as
ThreadLocals, if you think of continue
(the asynchronous sequence operator)
as semicolon (the synchronous sequence operator).
Because it's not meaningful to inherit control from two places, Locals don't have to worry about having to merge two Contexts.
Note: the implementation is optimized for situations in which save and restore optimizations are dominant.
Managed[T]
is a resource of type T
which lifetime is explicitly managed.
Managed[T]
is a resource of type T
which lifetime is explicitly managed.
It is created with make()
. Composite resources, which lifetimes are managed
together, are created by the use of flatMap
, ensuring proper construction and
teardown of the comprised resources.
Exceedingly useful for writing well-behaved tests that need control over a Timer.
Exceedingly useful for writing well-behaved tests that need control over a Timer. This is due to it playing well with the Time manipulation methods such as Time.withTimeAt, Time.withCurrentTimeFrozen, and so on.
See the cookbook for examples.
A Monitor is a composable exception handler.
A Monitor is a composable exception handler. It is independent of position, divorced from the notion of a call stack. Monitors do not recover values from a failed computations: It handles only true exceptions that may require cleanup.
AbstractMonitor for an API friendly to creating instances from Java.
Wraps an exception that happens when handling another exception in a monitor.
A Future which can never be satisfied and is thus always in the pending state.
A Future which can never be satisfied and is thus always in the pending state.
Future.never for an instance of it.
A NullTimer is not a timer at all: it invokes all tasks immediately and inline.
A writeable com.twitter.util.Future that supports merging.
A writeable com.twitter.util.Future that supports merging. Callbacks (responders) of Promises are scheduled with com.twitter.concurrent.Scheduler.
A Promise is in one of six states: Waiting
, Interruptible
,
Interrupted
, Transforming
, Done
and Linked
where Interruptible
,
Interrupted
, and Transforming
are variants of Waiting
to deal with future
interrupts. Promises are concurrency-safe, using lock-free operations
throughout. Callback dispatch is scheduled with Scheduler.
Waiters (i.e., continuations) are stored in a Promise.WaitQueue and executed in the LIFO order.
Promise.become
merges two promises: they are declared equivalent.
become
merges the states of the two promises, and links one to the
other. Thus promises support the analog to tail-call elimination: no
space leak is incurred from flatMap
in the tail position since
intermediate promises are merged into the root promise.
A Timer that proxies methods to self
.
Java adaptation of Var[T] with Updatable[T] with Extractable[T]
.
An abstract ProxyTimer that provides callback methods which are called when a task takes longer than the specified maximum runtime or if a task is observed to be taking longer than the specified maximum runtime.
An abstract ProxyTimer that provides callback methods which are called when a task takes longer than the specified maximum runtime or if a task is observed to be taking longer than the specified maximum runtime.
This makes assumptions that the underlying Timer
will execute tasks
sequentially in order to catch slow running tasks during execution. If the
underlying Timer
executes tasks in parallel the callback slowTaskExecuting
will become unreliable. However, the slowTaskCompleted
callback will remain
reliable but must be a thread-safe implementation.
Observation of slow task execution is performed when scheduling more work to
avoid the overhead of another thread or timer checking on tasks. This results
in lower overhead but means that slow running tasks may not be observed while
executing. However, they will trigger a callback to the slowTaskCompleted
regardless of whether additional work is scheduled.
A stopwatch may be used to measure elapsed time.
Representation of storage units.
Representation of storage units.
Use either StorageUnit.fromX
or implicit conversions
from Long
and Int
to construct instances.
import com.twitter.conversions.StorageUnitOps._ import com.twitter.util.StorageUnit val size: StorageUnit = 10.kilobytes
Operations can cause overflows of the Long
used to represent the
number of bytes.
While all the methods in this abstraction are prefixed according to the International System of Units (kilo-, mega-, etc), they actually operate on the 1024 scale (not 1000).
An absolute point in time, represented as the number of nanoseconds since the Unix epoch.
An absolute point in time, represented as the number of nanoseconds since the Unix epoch.
TimeFormat for converting to and from String
representations.
Stopwatch for measuring elapsed time.
Duration for intervals between two points in time.
A thread-safe wrapper around a SimpleDateFormat object.
A thread-safe wrapper around a SimpleDateFormat object.
The default timezone is UTC.
A common trait for time-like values.
A common trait for time-like values. It requires a companion
TimeLikeOps
module. TimeLike
s are finite, but they must always
have two sentinels: Top
and Bottom
. These act like positive
and negative infinities: Arithmetic involving them preserves their
values, and so on.
TimeLike
s are Long
-valued nanoseconds, but have different
interpretations: Duration
s measure the number of nanoseconds
between two points in time, while Time
measure the number of
nanoseconds since the Unix epoch (1 January 1970 00:00:00 UTC).
TimeLike behave like boxed java Double values with respect
to infinity and undefined values. In particular, this means that a
TimeLike
's Undefined
value is comparable to other values. In
turn this means it can be used as keys in maps, etc.
Overflows are also handled like doubles.
Timers are used to schedule tasks in the future.
Timers are used to schedule tasks in the future. They support both one-shot and recurring tasks.
Timers propagate Local state, including the Monitor, from when the task is scheduled to when it is run.
Scheduling tasks with Timers should rarely be done directly; for example, when programming with Futures, prefer using Future.sleep.
MockTimer for use in tests that require determinism.
TimerTasks represent pending tasks scheduled by a Timer.
A token bucket is used to control the relative rates of two processes: one fills the bucket, another empties it.
This class represents a computation that can succeed or fail.
This class represents a computation that can succeed or fail. It has two concrete implementations, Return (for success) and Throw (for failure)
Denotes an updatable container.
Vars are values that vary over time.
Vars are values that vary over time. To create one, you must give it an initial value.
val a = Var[Int](1)
A Var created this way can be sampled to retrieve its current value,
println(Var.sample(a)) // prints 1
or, invoked to assign it new values.
a.update(2) println(Var.sample(a)) // prints 2
Vars can be derived from other Vars.
val b = a.flatMap { x => Var(x + 2) } println(Var.sample(b)) // prints 4
And, if the underlying is assigned a new value, the derived Var is updated. Updates are computed lazily, so while assignment is cheap, sampling is where we pay the cost of the computation required to derive the new Var.
a.update(1) println(Var.sample(b)) // prints 3
A key difference between the derived Var and its underlying is that derived
Vars can't be assigned new values. That's why b
, from the example above,
can't be invoked to assign it a new value, it can only be sampled.
There are no well-defined error semantics for Var. Vars are computed lazily, and the updating thread will receive any exceptions thrown while computing derived Vars. Note: There is a Java-friendly API for this trait: com.twitter.util.AbstractVar.
,Vars do not always perform the minimum amount of re-computation.
A witness is the recipient of Event.
A witness is the recipient of Event.
Note: There is a Java-friendly API for this trait: com.twitter.util.AbstractWitness.
A Java analog of Event[A]()
.
A config object contains vars for configuring an object of type T, and an apply() method which turns this config into an object of type T.
A config object contains vars for configuring an object of type T, and an apply() method which turns this config into an object of type T.
The trait also contains a few useful implicits.
You can define fields that are required but that don't have a default value with: class BotConfig extends Config[Bot] { var botName = required[String] var botPort = required[Int] .... }
Optional fields can be defined with: var something = optional[Duration]
Fields that are dependent on other fields and have a default value computed from an expression should be marked as computed:
var level = required[Int] var nextLevel = computed { level + 1 }
(Since version ) use a Plain Old Scala Object
Note: There is a Java-friendly API for this object: com.twitter.util.Activities.
Synchronously await the result of some action by blocking the current thread.
Synchronously await the result of some action by blocking the current thread.
The two main uses of Await
are (a) you have synchronous code that needs to
wait on some action performed by asynchronous code, or (b) you have synchronous code
that needs to wait on some action performed on a thread pool or otherwise a different
thread.
A common type of Awaitable
is the com.twitter.util.Future.
In the context of an event loop (such as when you are on a Finagle thread), never synchronously wait for completion - favoring asynchronous methods such as combinators or callbacks registered on a Future.
Efficient conversion between Longs and base 64 encoded strings.
Efficient conversion between Longs and base 64 encoded strings.
This is intended for use in e.g. cache keys.
Note: There is a Java-friendly API for this object: com.twitter.util.Closables
.
Simple helper to read authentication credentials from a text file.
Simple helper to read authentication credentials from a text file.
The file's format is assumed to be trivialized yaml, containing lines of the form
.
Keys can be any word character or '-' and values can be any character except new lines.
key: value
Diffable defines common type class instances for Diffable.
Note: There is a Java-friendly API for this object: com.twitter.util.Events.
The user guide on concurrent programming with Futures.
Futures for Java-friendly APIs.
Note: There is a Java-friendly API for this object: com.twitter.util.FuturePools.
Twitter Future utility methods for ease of use from java
Defines the (Future)-Local
monitor as well as some monitor
utilities.
Defines the (Future)-Local
monitor as well as some monitor
utilities.
Java users should use the Monitors
class.
A trivial implementation of Stopwatch for use as a null object.
A trivial implementation of Stopwatch for use as a null object.
All calls to Stopwatch.start() return an Stopwatch.Elapsed instance that always returns Duration.Bottom for its elapsed time.
NilStopwatch.get
for accessing this instance from Java.
A monitor that always fails to handle an exception.
A monitor that always fails to handle an exception. Combining this with any other Monitor will simply return the other Monitor effectively removing NullMonitor from the chain.
A generator of random local java.net.InetSocketAddress objects with ephemeral ports.
The system Stopwatch measures elapsed time using System.nanoTime
.
The system Stopwatch measures elapsed time using System.nanoTime
.
Note that it works well with unit tests by respecting time manipulation on Time.
Stopwatches for Java APIs.
Java APIs for Stopwatch.
By using Time.now in your program instead of
System.currentTimeMillis
unit tests are able to adjust
the current time to verify timeouts and other time-dependent
behavior, without calling sleep
, and providing deterministic
tests.
By using Time.now in your program instead of
System.currentTimeMillis
unit tests are able to adjust
the current time to verify timeouts and other time-dependent
behavior, without calling sleep
, and providing deterministic
tests.
The current time can be manipulated via Time.withTimeAt, Time.withCurrentTimeFrozen, Time.withTimeFunction and Time.sleep.
While now
is not a "global" it is however properly propagated through
to other code via the standard usage of Locals throughout util
.
Specifically, code using Futures, FuturePools,
and MockTimers will have their code see the manipulated
values.
val time = Time.fromMilliseconds(123456L) Time.withTimeAt(time) { timeControl => assert(Time.now == time) // you can control time via the `TimeControl` instance. timeControl.advance(2.seconds) FuturePool.unboundedPool { assert(Time.now == time + 2.seconds) } }
TimeFormat for converting to and from String
representations.
Stopwatch for measuring elapsed time.
Duration for intervals between two points in time.
The Try type represents a computation that may either result in an exception or return a success value.
The Try type represents a computation that may either result in an exception or return a success value. It is analogous to the Either type but encodes common idioms for handling exceptional cases (such as rescue/ensure which is analogous to try/finally).
A java.text.SimpleDateFormat
that avoids confusion between YYYY and yyyy.
A java.text.SimpleDateFormat
that avoids confusion between YYYY and yyyy.
One should never use YYYY (week year) unless the format also includes the week of year.
Note: There is a Java-friendly API for this object: com.twitter.util.Vars.
Note: There is Java-friendly API for this object: com.twitter.util.Witnesses.
You can import Config._ if you want the auto-conversions in a class that does not inherit from trait Config.
You can import Config._ if you want the auto-conversions in a class that does not inherit from trait Config.
(Since version ) use a Plain Old Scala Object
Activity, like Var, is a value that varies over time; but, richer than Var, these values have error and pending states. They are useful for modeling a process that produces values, but also intermittent failures (e.g. address resolution, reloadable configuration).
As such, an Activity can be in one of three states:
An Activity may transition between any state at any time. They are typically constructed from Events, but they can also be constructed without arguments.
As you can see, Activities start in a Pending state. Attempts to sample an Activity that is pending will fail. Curiously, the constructor for an Activity also returns a Witness.
Recall that a Witness is the interface to something that you can send values to; and in this case, that something is the Activity.
(For implementers, it may be useful to think of Activity as a monad transformer for an Op monad over Var where Op is like a Try with an additional pending state.)