* well as a simple framework for helping to make sure that assertions failing in generated threads
 * cause the associated test that generated them to itself fail (which JUnit does not otherwise
 * arrange). The rules for creating such tests are:
 *
 * <ol>
 *   <li>All assertions in code running in generated threads must use the forms {@link #threadFail},

  }

  /**
   * Creates an empty multiset containing the given initial elements, sorted according to the
   * elements' natural order.
   *
   * <p>This implementation is highly efficient when {@code elements} is itself a {@link Multiset}.
   *
   * <p>The type specification is {@code <E extends Comparable>}, instead of the more specific
   * {@code <E extends Comparable<? super E>>}, to support classes defined without generics.
   */

 * <p>The implementation detects cycles by constructing a directed graph in which each lock
 * represents a node and each edge represents an acquisition ordering between two locks.
 *
 * <ul>
 *   <li>Each lock adds (and removes) itself to/from a ThreadLocal Set of acquired locks when the
 *       Thread acquires its first hold (and releases its last remaining hold).
 *   <li>Before the lock is acquired, the lock is checked against the current set of acquired

      createDirectedGraph("ab", "ac", "bd", "cd");

  /**
   * Same as {@link #DIAMOND_GRAPH}, but with an extra c->a edge and some self edges:
   *
   * <pre>{@code
   *   a<>
   *  / \\
   * b   c
   *  \ /
   *   d<>
   * }</pre>
   *
   * {@code <>} indicates a self-loop
   */
  private static final SuccessorsFunction<Character> MULTI_GRAPH =
      createDirectedGraph("aa", "dd", "ab", "ac", "ca", "cd", "bd");

      long mulMod(long a, long b, long m) {
        /*
         * lowasser, 2015-Feb-12: Benchmarks suggest that changing this to UnsignedLongs.remainder
         * and increasing the threshold to 2^32 doesn't pay for itself, and adding another enum
         * constant hurts performance further -- I suspect because bimorphic implementation is a
         * sweet spot for the JVM.
         */
        return (a * b) % m;
      }

 * allocations in many common cases.
 *
 * <p>The message string is not formatted unless the exception will be thrown, so the cost of the
 * string formatting itself should not be a concern.
 *
 * <p>As with any performance concerns, you should consider profiling your code (in a production
 * environment if possible) before spending a lot of effort on tweaking a particular element.
 *

 *     .addEqualityGroup(new User("page"), new User("page"))
 *     .addEqualityGroup(new User("sergey"))
 *     .testEquals();
 * </pre>
 *
 * <p>This tests:
 *
 * <ul>
 *   <li>comparing each object against itself returns true
 *   <li>comparing each object against null returns false
 *   <li>comparing each object against an instance of an incompatible class returns false

    // sanity check on construction of copyOfModifiedSet
    assertThat(wrappedSet).isEqualTo(copyOfModifiedSet);

    // setToTest should throw when it calls equals(), or equals is called on it, except for itself
    assertThat(setToTest).isEqualTo(setToTest);
    assertThrows(IllegalStateException.class, () -> setToTest.equals(wrappedSet));
    assertThrows(IllegalStateException.class, () -> setToTest.equals(copyOfWrappedSet));

    // sanity check on construction of copyOfModifiedSet
    assertThat(wrappedSet).isEqualTo(copyOfModifiedSet);

    // setToTest should throw when it calls equals(), or equals is called on it, except for itself
    assertThat(setToTest).isEqualTo(setToTest);
    assertThrows(IllegalStateException.class, () -> setToTest.equals(wrappedSet));
    assertThrows(IllegalStateException.class, () -> setToTest.equals(copyOfWrappedSet));

    return new HashMultiset<>(distinctElements);
  }

  /**
   * Creates a new {@code HashMultiset} containing the specified elements.
   *
   * <p>This implementation is highly efficient when {@code elements} is itself a {@link Multiset}.
   *
   * @param elements the elements that the multiset should contain
   */
  public static <E extends @Nullable Object> HashMultiset<E> create(
      Iterable<? extends E> elements) {