name: Feature Enhancement Request
description: I want to make an existing feature better
labels: ["type=enhancement"]
body:
  - type: markdown
    attributes:
      value: >
        Filing feature requests is one of the most popular ways to contribute to Guava.


        Be aware, though: most feature requests are not accepted, even if they're suggested by
        a full-time Guava team member. [Feedback](https://stackoverflow.com/a/4543114) from our

     * have the same nullness as E." Since we can't, we declare it to return nullable elements, and
     * we can override it in our non-null-guaranteeing subtypes to present a better signature to
     * their users.
     *
     * However, the checker *we* use has this special knowledge about `Collection.toArray()` anyway,

 *
 * <p>The {@link #count} and {@link #size} implementations all iterate across the set returned by
 * {@link Multiset#entrySet()}, as do many methods acting on the set returned by {@link
 * #elementSet()}. Override those methods for better performance.
 *
 * @author Kevin Bourrillion
 * @author Louis Wasserman
 */
@GwtCompatible
@ElementTypesAreNonnullByDefault
abstract class AbstractMultiset<E extends @Nullable Object> extends AbstractCollection<E>

   *
   * @throws IllegalArgumentException if the resource is not found
   */
  @CanIgnoreReturnValue // being used to check if a resource exists
  // TODO(cgdecker): maybe add a better way to check if a resource exists
  // e.g. Optional<URL> tryGetResource or boolean resourceExists
  public static URL getResource(String resourceName) {
    ClassLoader loader =
        MoreObjects.firstNonNull(

      afe.initCause(ie);
      throw afe;
    }
  }

  /**
   * Spin-waits up to the specified number of milliseconds for the given thread to enter a wait
   * state: BLOCKED, WAITING, or TIMED_WAITING.
   */
  void waitForThreadToEnterWaitState(Thread thread, long timeoutMillis) {
    long startTime = System.nanoTime();
    for (; ; ) {

  }

  /**
   * Not supported. Use {@link #naturalOrder}, which offers better type-safety, instead. This method
   * exists only to hide {@link ImmutableMap#builder} from consumers of {@code ImmutableSortedMap}.
   *
   * @throws UnsupportedOperationException always
   * @deprecated Use {@link ImmutableSortedMap#naturalOrder}, which offers better type-safety.
   */
  @DoNotCall("Use naturalOrder")
  @Deprecated

   * There is no need for a blocking lock; when the lock is not
   * available, threads try other slots (or the base).  During these
   * retries, there is increased contention and reduced locality,
   * which is still better than alternatives.
   *
   * Per-thread hash codes are initialized to random values.
   * Contention and/or table collisions are indicated by failed
   * CASes when performing an update operation (see method

      }
      // uncheckedCastNullableTToT is safe because bufferSize > 0.
    } else if (comparator.compare(elem, uncheckedCastNullableTToT(threshold)) < 0) {
      // Otherwise, we can ignore elem; we've seen k better elements.
      buffer[bufferSize++] = elem;
      if (bufferSize == 2 * k) {
        trim();
      }
    }
  }

  /**

   * completely unused, and an expensive acquire(100) request comes. It would be nonsensical to just
   * wait for 100 seconds, and /then/ start the actual task. Why wait without doing anything? A much
   * better approach is to /allow/ the request right away (as if it was an acquire(1) request
   * instead), and postpone /subsequent/ requests as needed. In this version, we allow starting the

    Builder<String, Integer> builder =
        new Builder<String, Integer>()
            .put("one", 1)
            .put("one", 1); // throwing on this line would be even better

    try {
      builder.build();
      fail();
    } catch (IllegalArgumentException expected) {
      assertThat(expected.getMessage()).contains("one");
    }
  }

  public void testOf() {