util
Abstract Closable class for Java compatibility.
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.
An Activity is a handle to a concurrently running process, producing T-typed values.
An Activity is a handle to a concurrently running process, producing T-typed values. An activity is in one of three states:
An activity may transition between any state at any time.
(The observant reader will notice that this is really a monad transformer for an Op monad over Var where Op is like a Try with an additional pending state.)
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 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.time._ 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 instantaneous values, defined only at particular instants in time (cf.
Events are instantaneous values, defined only at particular instants in time (cf. Vars, which are defined at all times). It is possible to view Events as the discrete counterpart to Var's continuous nature.
Events are observed by registering Witnesses to which the Event's values are notified.
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,
TransformingInterrupted, and are variants of Waiting to deal with future
interrupts. Promises are concurrency-safe, using lock-free operations
throughout. Callback dispatch is scheduled with
com.twitter.concurrent.Scheduler.
Waiters are stored as a com.twitter.util.Promise.K. Ks
(mnemonic: continuation) specifies a depth. This is used to
implement Promise chaining: a callback with depth d is invoked only
after all callbacks with depth < d have already been invoked.
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 number of optimizations are employed to conserve space: we pay
particular heed to the JVM's object representation, in particular for
OpenJDK (HotSpot) version 7 running on 64-bit architectures with
compressed OOPS. See comments on com.twitter.util.Promise.State
for details.
A Timer that proxies methods to self.
Java adaptation of Var[T] with Updatable[T] with Extractable[T].
RichU64String parses string as a 64-bit unsigned hexadecimal long, outputting a signed Long or a byte array.
RichU64String parses string as a 64-bit unsigned hexadecimal long, outputting a signed Long or a byte array. Valid input is 1-16 hexadecimal digits (0-9, a-z, A-Z).
NumberFormatException if string is not a non-negative hexadecimal
string
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.storage._ 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).
Test mixin that creates a temporary thread-local folder for a block of code to execute in.
Test mixin that creates a temporary thread-local folder for a block of code to execute in. The folder is recursively deleted after the test.
Note, the com.twitter.util.io package would be a better home for this trait.
Note that multiple uses of TempFolder cannot be nested, because the temporary directory is effectively a thread-local global.
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. TimeLikes 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.
TimeLikes are Long-valued nanoseconds, but have different
interpretations: Durations 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.
Trait Var represents a variable.
Trait Var represents a variable. It is a reference cell which is composable: dependent Vars (derived through flatMap) are recomputed automatically when independent variables change -- they implement a form of self-adjusting computation.
Vars are observed, notifying users whenever the variable changes.
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 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
A classifier of non-fatal Exceptions.
A classifier of non-fatal Exceptions.
Developers should prefer using scala.util.control.NonFatal from the
Scala standard library.
(Since version 2016-11-21) Use scala.util.control.NonFatal instead
Scala added NonFatal to the standard library in Scala 2.10, while
Twitter's util needed to provide this for users who were still on
Scala 2.9 at the time.
Scala's NonFatal for usage notes.