* #descendingMultiset()} will not reflect any changes you make to the behavior of methods such as
   * {@link #add(Object)} or {@link #pollFirstEntry}. This skeleton implementation correctly
   * delegates each of its operations to the appropriate methods of this {@code
   * ForwardingSortedMultiset}.
   *
   * <p>In many cases, you may wish to override {@link #descendingMultiset()} to return an instance

   * checkNotNull *should* be annotated to require it to be non-null.
   *
   * However, for a variety of reasons, Google developers have written a ton of code over the past
   * decade that assumes that they can use checkNotNull for non-precondition checks. I had hoped to
   * take a principled stand on this, but the amount of such code is simply overwhelming. To avoid

  //    - implement Serializable
  //    - redo the API to be as close to identical to ReentrantLock as possible,
  //      since, after all, this class is also a reentrant mutual exclusion lock!?

  /*
   * One of the key challenges of this class is to prevent lost signals, while trying hard to
   * minimize unnecessary signals. One simple and correct algorithm is to signal some other waiter

   * first one specified is included.
   *
   * <p>Despite the method name, this method attempts to avoid actually copying the data when it is
   * safe to do so. The exact circumstances under which a copy will or will not be performed are
   * undocumented and subject to change.
   *

/**
 * A map entry which forwards all its method calls to another map entry. Subclasses should override
 * one or more methods to modify the behavior of the backing map entry as desired per the <a
 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
 *
 * <p><b>Warning:</b> The methods of {@code ForwardingMapEntry} forward <i>indiscriminately</i> to

     *
     * We rely on checkers to implement special cases to catch dangerous calls to join(), etc. based
     * on what they know about the particular Joiner instances the calls are performed on.
     *
     * (In addition to useForNull, we also offer skipNulls. It, too, tolerates null inputs, but its
     * tolerance is implemented differently: Its implementation avoids calling this toString(Object)
     * method in the first place.)

   *
   * <p>Despite the method name, this method attempts to avoid actually copying the data when it is
   * safe to do so. The exact circumstances under which a copy will or will not be performed are
   * undocumented and subject to change.
   *
   * @throws NullPointerException if any key or value in {@code map} is null
   * @throws IllegalArgumentException if any two keys are equal according to the comparator
   */

 *       to check for a cycle that reaches the lock to be acquired. If no cycle is detected, a new
 *       "safe" edge is created.
 *   <li>If a cycle is detected, an "unsafe" (cyclic) edge is created to represent a potential
 *       deadlock situation, and the appropriate Policy is executed.
 * </ul>
 *

 * com.google.common.collect.Ordering} (otherwise).
 *
 * <h3>Relationship to {@code Ordering}</h3>
 *
 * <p>In light of the significant enhancements to {@code Comparator} in Java 8, the overwhelming
 * majority of usages of {@code Ordering} can be written using only built-in JDK APIs. This class is
 * intended to "fill the gap" and provide those features of {@code Ordering} not already provided by
 * the JDK.
 *

   *
   * <ul>
   *   <li>{@code getStackTrace} takes {@code stackSize} time to return but then negligible time to
   *       retrieve each element of the returned list.
   *   <li>{@code lazyStackTrace} takes negligible time to return but then {@code 1/stackSize} time
   *       to retrieve each element of the returned list (probably slightly more than {@code
   *       1/stackSize}).
   * </ul>
   *