[split] util-app: Improve the Scaladocs for com.twitter.app.Flag and friends

In describing flag behavior in a support email, I found that there are
methods and idiosyncrasies of the flag library that could have clearer
documentation. This change rewords and adds a bunch of Scaladocs within
Flag.scala.

RB_ID=367255
[split] s/GUILD/CSL/ for all CONFIG.ini's

RB_ID=378107
TBR=true
[split] Signal the deprecation of com.twitter.util.Bijection.

Based on E-Mail thread: com.twitter.util.Bijection vs. com.twitter.Bijection

RB_ID=376008
[split] Add additional handlers to Logging trait.

Problem

There is no way to override the handlers that the default LoggerFactory uses in the Logging trait. The result is that if someone wants to add a handler to the root logger factory (e.g. for LogLens) they need to override and copy paste the whole method.

Solution

Add a method called handlers that can be overridden if needed. This initiates one handler by default, but it can be overridden if we need to add more handlers.

Result

It is now possible to easily configure LogLens for all applications.

RB_ID=375114
[split] Add U(32|64)(BE|LE) to Buf

RB_ID=361451
[split] util-core: Fix MockTimer#schedule(Duration)(=> Unit)'s cancel

Problem
MockTimer#schedule(Duration)(=> Unit)'s tasks cannot be canceled after it has already ticked.

Solution
Return a task which when cancelled, stops the entire task from continuing.

Result
MockTimer#schedule(Duration)(=> Unit)'s tasks no longer continue past when they should have stopped.

RB_ID=377357
[split] finagle-mux: GC Avoidance Algorithm

Problem

In order to choose when we do GC avoidance, we need to guess in
advance when the JVM will do GC automatically, and respond properly.
As a first-order heuristic, we're going to use an exponential
weighted moving average.

Solution

We wrote a jvm GC heuristic for finagle, and use it to decide when
to drain.  After we've drained, we try to force a minor gc, and
then undrain.

Result

We have all of the pieces in place to detect how to set our leases
properly.

RB_ID=371522
[split] util-app: Don't kill the JVM on flag-parsing failure

Problem

Upon failure to parse a flag, c.t.app.App invokes `System.exit(1)`. It
seems too heavy-handed to force JVM death rather than have the caller
handle a RuntimeException (which would exit the process in the normal
case).

Solution

Introduce `FlagParseResult` case classes to represent the outcome of
flag parsing. Using these, a `Flags.parseArgs` method is provided to
serve as the preferred entry-point for flag parsing. `Flags.parse` is
deprecated and `Flags.parseOrExit1` is written in terms of the new
method, `Flags.parseArgs`.

This commit also adds some polish to the format of usage output
strings.

RB_ID=378167
[split] util-core: Fix update-after-interrupt race condition in AsyncSemaphore

Problem

Production logs from a rate-limiting service indicated that a Promise
is being double-set somewhere within
RequestSemaphoreFilter/AsyncSemaphore.

Solution

We think that the issue is being caused by a race between invocations
of the interrupt handler set in `AsyncSemaphore.acquire` and the
unsynchronized `Promise.setValue` in `AsyncSemaphore.release`. With
this change, `release` is synchronized in its entirety, rather than
just the queue-poll.

RB_ID=387575
[split] util-core: src/main/java dependency on src/main/scala  - util-core: src/main/java uses classes from src/main/scala, need a dependency to avoid missing dependency error

RB_ID=388979
[split] util-core: Catch InterruptedException in Closable collector thread

Problem

A report on the finaglers mailing list indicated that the ThriftClient
class in finagle-example fails to terminate cleanly when run in SBT [1].
I think this has to do with SBT's handling of System.exit, explained in [2].

> "User code is run with a custom SecurityManager that throws a custom
> SecurityException when System.exit is called. This exception is caught by sbt.
> sbt then disposes of all top-level windows, interrupts (not stops) all
> user-created threads, and handles the exit code."

Thus even though daemon threads should be killed outright on process
termination, SBT instead interrupts them. This causes the Closable
collector thread (which is blocked on `ReferenceQueue.remove()`) to
log and throw a fatal exception.

Solution

Add a pass-through case for InterruptedException within the collector
thread.

[1] https://groups.google.com/forum/#!topic/finaglers/Hq1CHqeeLgI
[2] http://www.scala-sbt.org/release/docs/Detailed-Topics/Running-Project-Code.html

RB_ID=278895
[split] bump util to 6.18.1-SNAPSHOT

RB_ID=391383
TBR=true
NO-QUEUE=true