[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