Java's analog of Scala's com.twitter.util.CloseAwaitably.

In order to make it more Java-friendly, the abstract method com.twitter.util.AbstractCloseAwaitably#onClose is used instead of a higher-order function in Scala version.

An example usage looks as follows.

  class A extends AbstractCloseAwaitably {
    public Future onClose(Time deadline) {
      return Future.Done();
    
  }

}

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:

• Pending: output is pending;
• Ok: an output is available; and
• Failed: the process failed with an exception.

An Activity may transition between any state at any time. They are typically constructed from Events, but they can also be constructed without arguments.

val (activity, witness) = Activity[Int]()
println(activity.sample()) // throws java.lang.IllegalStateException: Still pending

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.

witness.notify(Return(1))
println(activity.sample()) // prints 1

(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.)

Wait for the result of some action. Awaitable is not used directly, but through the Await object.

A utility for encoding strings and byte arrays to a MIME base64 string, and decoding from strings encoded in MIME base64 to byte arrays.

The encoding for strings is UTF-8.

A utility for encoding strings and byte arrays to a URL-safe base64 string, and decoding from strings encoded in base64 to byte arrays.

The encoding for strings is UTF-8.

A thread-safe ThriftSerializer that uses TBinaryProtocol.

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.

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.

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.

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 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.ClosableOnce.

class MyClosable extends ClosableOnce with CloseOnceAwaitably {
  def closeOnce(deadline: Time) = {
    // close the resource
  }
}

A Future that is already completed.

These are cheap in construction compared to Promises.

Resource Management

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

Disposable/Managed Semantics

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. 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.

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.

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. 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.

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:

• Pending, the computation has not yet completed
• Satisfied successfully, with a result of type T (a Return)
• Satisfied by a failure, with a 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.

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.

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.

A collection of utilities for encoding strings and byte arrays to and decoding from strings compressed from with gzip.

This trait is thread-safe because there are no streams shared outside of method scope, and therefore no contention for shared byte arrays.

The encoding for strings is UTF-8.

gzipping inherently includes base64 encoding (the GZIP utilities from java will complain otherwise!)

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.

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. 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. This is due to it playing well with the Time manipulation methods such as Time.withTimeAt, Time.withCurrentTimeFrozen, and so on.

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 failed computations: It handles only true exceptions that may require cleanup.

A Future which can never be satisfied and is thus always in the pending state.

A writeable com.twitter.util.Future that supports merging. Callbacks (responders) of Promises are scheduled with com.twitter.concurrent.Scheduler.

Implementation details

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 com.twitter.concurrent.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.

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.

Representation of storage units.

Use either StorageUnit.fromX or com.twitter.conversions.storage implicit conversions from Long and Int to construct instances.

import com.twitter.conversions.StorageUnitOps._
import com.twitter.util.StorageUnit

val size: StorageUnit = 10.kilobytes

An absolute point in time, represented as the number of nanoseconds since the Unix epoch.

A parser and formatter for Time instances. Instances of this class are immutable and threadsafe. Use TimeFormatter$.apply to construct instances from DateTimeFormatter-compatible pattern strings.

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. 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.

This class represents a computation that can succeed or fail. It has two concrete implementations, Return (for success) and Throw (for failure)

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.

A witness is the recipient of Event.

Note: There is a Java-friendly API for this trait: com.twitter.util.AbstractWitness.

WrappedValue is a marker interface intended for use by case classes wrapping a single value. The intent is to signal that the underlying value should be directly serialized or deserialized ignoring the wrapping case class.

WrappedValue is a Universal Trait so that it can be used by value classes.

Usage

case class WrapperA(underlying: Int) extends WrappedValue[Int]
case class WrapperB(underlying: Int) extends AnyVal with WrappedValue[Int]

A thread-safe wrapper around a SimpleDateFormat object.

This class is deprecated in favor of TimeFormatter. When moving from this class to TimeFormatter, be mindful that there are some subtle differences in patterns between java.text.SimpleDateFormat used by this class and DateTimeFormatter used by TimeFormatter. Pattern character 'u' has a different meaning. Character 'a' cannot be repeated, and numerals for day of week produced by 'e' and 'c' can count from either Sunday or Monday depending on locale. Time zones might be parsed differently, and DateTimeFormatter defines several different time zone pattern characters with various behaviors. Consult the Javadoc for java.text.SimpleDateFormat and DateTimeFormatter for details. Finally, the parse method in this class throws a java.text.ParseException while the one in TimeFormatter throws DateTimeParseException. If you rely on catching exceptions from parsing, you will need to change the type of the exception. Note that built in Time.at and Time.fromRss keep throwing java.text.ParseException for backwards compatibility.

The default timezone is UTC.