[split] [util-core] make Function classes covariant

The scala function traits are covariant in their return type.
This changes the java interfaces to be covariant as well.

RB_ID=318249
[split] util/Future: short-circuit `within` and `raiseWithin` if Future is already satisfied

RB_ID=322845
[split] KeyValueRepository adaptor for Stitch

RB_ID=319659
[split] [util-core] mark tests flaky due to JDK upgrade

RB_ID=324329
TBR=true
NO-QUEUE=true
[split] Add com.twitter.io.Charsets and replace the use of org.jboss.netty.util.CharsetUtil

Motivation:

As a part of the first step for Netty 3 -> 4 migration, we should not
import nor use CharsetUtil.

Related issue: NETTY-18

Modifications:

- Introduce a new object 'com.twitter.io.Charsets' that replaces
  'org.jboss.netty.util.CharsetUtil'.
- Replace the use of CharsetUtil with Charsets in finagle and util

Result:

No classes under finagle and util use CharsetUtil:

  $ grep -rFl CharsetUtil finagle util | grep -vP '\.class$'
  finagle/doc/src/sphinx/code/client-server-anatomy/Netty3.scala

Note that Netty3.scala is an example that explains how Netty 3 works,
so I didn't change it.

RB_ID=320575
[split] Parse names into trees; introduce separate evaluation.

Currently, names are flat -- sets of socket addresses -- leaving no
room for interpretation in the client. For example, a client might
wish to fail-over to an alternative name should the active destination
fail; we may also wish to support proportional balancing across
several zones.

This change represents names as trees--type NameTree[T] denotes name
trees with T-typed leaves--whose interior nodes may be composed
concurrently (representing a union) or as a set of alternatives (in
order of preference).

As it turns out, it is possible to encode our current abstract naming
mechanisms using name trees. In particular, Dtabs become a sort of
context under which name trees are bound. Such contexts are called
Namers, and provide an expansive lookup function: Path =>
NameTree[Path]. Binding relative to a namer is thus a process of
reaching a fixpoint while looking up paths using that namer. Dtab is
reimplemented as Namer.

Once a NameTree[Path] is fully bound--i.e. it has reached a fixpoint--
the NameTree[Path] is *evaluated* in order produce a concrete,
flattened set of addresses to which requests may be dispatched.
Currently evaluation follows a simple logic: the first nonempty
alternative is picked while unions are preserved.

Since we cannot resolve a Path directly into an Internet address, we
interpret paths beginning with /$/inet/ specially. The residual path
following denotes the IP host/port. (Technically, a port is not an IP
property, but we paper over this detail here, since we aim at least
currently to support only TCP and UDP addressing.)

We see that NameTrees act as a unification mechanism: Dtabs are
implemented as Namers and its semantics encoded directly into
NameTrees (using alternative composition). Furthemore, NameTrees
naturally tackle residual paths, which were only partially supported
previously, without introducing any further concepts or syntax. The
whole process of binding and evaluating an abstract name is tackled
entirely using NameTrees, using exactly one namespace.

Path names also have a concrete syntax with grammar

    tree       ::= name
                   weight '*' tree
                   tree '&' tree
                   tree '|' tree
                   '(' tree ')'

    name       ::= path | '~' | '$'

    path       ::= '/' labels

    labels     ::= label '/' label
                   label

    label      ::= litlabel | hexlabel

    hexlabel   ::= (\\x[a-f0-9][a-f0-9])+

    litlabel   ::= [0-9A-Za-z:.#$%-]+
    weight     ::= -?([0-9]++(\.[0-9]+*)?|[0-9]+*\.[0-9]++)([eE][+-]?[0-9]++)?[fFdD]?

As do Dtabs, which extend the above productions with

    dtab       ::= dentry ';' dtab | dentry
    dentry     ::= path '=>' tree

Some implementation notes:

 *	I had originally wanted to simply replace the 'Name'
	abstraction, but decided this would break too much. I think
	that with the current change, we can get away without a major
	version bump. (Since Dtabs, etc. were previously
	private[twitter].) It is, however, more complex than it needs
	to be because of it.

 *	I had weights, but took them out for now -- I'm still undecided
	on whether to keep these at the name level (so that evaluation
	results in a tree) or flatten them out as is done now in zk2.

 *	Activity is, in fact, a monad transformer over an 'Op' monad.
	I had the code arranged like this initially, but decided that
	this is simpler and more understandable, especially in the
	absence of more monad-generic code in util. If you're curious,
	though, you can see what it looks like:
		https://gist.github.com/mariusaeriksen/7343968dd75929458519

RB_ID=286441
TBR=true
[split] util-core: Comprehensive Scaladocs for Scheduler-related classes and traits

RB_ID=325807
[split] util-core: Add Local.let

Problem:
There's a perceived need for a reasoned API for scoping Locals to blocks of code.
There have been numerous issues caused by dodgy Local lifecycle management
(e.g. memory leaks).

Solution:
This change introduces `def let[U](Option[T])(=> U): U`, which allows one to
specify a value to be used for a given Local within the scope of a block. The
previous value of the Local is restored after completion of the block.

This change also moves some stuff around within Local.scala, adds Scaladocs, and
ports LocalSpec to ScalaTest.

Result:
We have a more rigorous API for using Locals with defined lifespans. This gist
shows how the ClientId code in finagle-thrift would be updated to use
`Local.let`: https://gist.github.com/evnm/cfff5bf8ca5876da2088

RB_ID=312945
[split] configbus-client:   Adds Client.nodeClient and Client.contentClient constructors.

decider:
  Adds DeciderStore.builder(defaultSource: VarSource[Buf])
  Modifies DeciderStoreBuilder to use Option for setting optional fields.

macaw-base:
  Adds Stats to GuiceApp

twitter-server-internal:
  Adds decider.experimental.configbus flag to Deciderable trait

util-core:
  Adds FailoverVarSource
  Adds VarSource.flatMap

RB_ID=320061
[split] util-core: Bump objectsize dependency to 0.0.10

Motivation:
New TwitterJDK report itself as "TwitterJDK..." instead of "OpenJDK..."
The objectsize library has a runtime check that ensure the name of the VM
is "OpenJDK..." or "Hotspot". The latest version 0.0.10 also whitelist TwitterJDK

Modification:
Bump objectsize version in pom.xml and 3rdparty/BUILD

Result:
Tests are passing

RB_ID=326627
TBR=true
[split] finagle-benchmark: Fix caliper failures due to new guava

Motivation
The recent version upgrade of guava (from 15 to 16) broke all our micro-benchmarks
because the (old) caliper library that we are using requires guava (ver<=15).

Modifications
- Force usage of guava 15 (in maven and pants)
- Update StatsReceiver benchmark
- Disable memory measuring for benchmarks that have non constant memory allocation pattern
- Clean-up inconsistent namespace

Result
All micro-benchmarks are now finishing without errors.

RB_ID=326239
[split] Revert "[util-core] mark tests flaky due to JDK upgrade"

Now that Steve's changes (04e66bc32c402067b905f1a9626d2266b5db4b68) is
science master, I'm reverting this changes I made a couple days ago.

RB_ID=326455
[split] util-core: Create a static Exception for use in `Future.raiseWithin`

Problem
We currently allocate a new Exception on every invocation of
`Future.raiseWithin`. This is unnecessarily wasteful.

Solution
This change creates a private, final, and stacktrace-less Exception to
the Future companion object for re-use in `raiseWithin`.

Result
Fewer allocations and less cpu time spent generating stacktraces in
`Future.raiseWithin`.

RB_ID=329189
[split] Future.select: fix inacurrate comments

RB_ID=329639
[split] bump util to 6.14.1-SNAPSHOT

RB_ID=331395
TBR=true
[split] ForkJoinScheduler: group tasks in local scheduler; split when blocking

Problem

The current ForkJoin scheduler forks all tasks locally. This typically
leads to very fine-grained work being scheduled directly by the FJ
pool.

Solution

We introduce a form of coarsening by using a
com.twitter.concurrent.LocalScheduler to schedule thread-local tasks.
During managed blocking, we flush the local schedule by forking their
tasks individually. This allows us to coarsen the work and prevent
over-stealing.

Results

Hopefully better performance on a typical Finagle service.

RB_ID=330121
[split] util-core: Fixes detachable semantics with ConstFuture Problem Promise.attached on ConstFutures didn't work as you'd expect, which would be that it would fulfil the Promise and then detach it.

Solution
Changes the parent.respond to execute outside of the class initialization.

Result
Promise.attached is significantly easier to reason about with ConstFutures.

RB_ID=331505
[split] Spool: Make lazier

Problem

The map/flatMap/++ combinators for Spool were not acting lazily, although that would be the expectation when a Spool is constructed using the lazy constructor. Consumers have built their own workarounds in a few places to deal with this behavior.

Solution

For implementation simplicity, all internal construction of Spools is now lazy via explicit calls to LazyCons. This is validated by tests with a poisoned tail. Additionally, new methods were added to take advantage of the laziness: takeWhile and force.

Result

map/flatMap/collect/++/etc act lazily, and consumer code has been simplified.

RB_ID=331015
[split] com.twitter.app.App: enforce close grace period

Problem

Apps will hang if their constituent parts do not succesfully close
within the deadline. This stems from the fact that Closable deadlines
are advisory.

Solution

Enforce the timeout.

RB_ID=332601
[split] Make com.twitter.finagle.Name an ADT

Problem

There is currently a proliferation of Name implementations which are
related in all sorts of convoluted ways. This is accidental complexity
due to the fact that the Name interface, being part of Finagle's
public API, remains sacrosanct -- at least for the moment.

Solution

This change tries to simplify things a little by making Name a proper
ADT with two variants: Name.Bound describes a bound address; Name.Free
is an unbound Name whose resolution is determined by a Namer. This
makes the relationships clear, and requires only a small API change.

It also makes clear that, in intermediate computation, there are two
levels of dynamism: the tree itself is dynamic; its nodes are
independently dynamic. There is still confusion between the
relationship of Var.{Neg, Pending, etc..} with that of
Activity.Ok(NameTree.{Neg, Empty}) | Activity.Pending, etc. This is
unfortunate -- ideally, we'd be able to pull all of that out of Addr,
and model it entirely as NameTrees. But this is about as far we can go
without making major API changes.

It also has a simplifying effect on Namer signatures. Namely, binding
is now more explicit:

	def lookup(path: Path): Activity[NameTree[Name]]
	def bind(tree: NameTree[Path]): Activity[NameTree[Name.Bound]]

and it is clear whence dynamism is derived.

I also took the opportunity to unify some of the naming (heh.) around this.
In particular, InterpretingFactory is now BindingFactory.

Result

Nicer API; no functionality changes.

RB_ID=330105
TBR=true