io.grpc.ExperimentalApi#com.google.errorprone.annotations.CanIgnoreReturnValue源码实例Demo

@CanIgnoreReturnValue
@Override
public int remove(@Nullable Object element, int occurrences) {
  if (occurrences == 0) {
    return count(element);
  }
  checkArgument(occurrences > 0, "occurrences cannot be negative: %s", occurrences);
  Count frequency = backingMap.get(element);
  if (frequency == null) {
    return 0;
  }
  int oldCount = frequency.get();
  int numberRemoved;
  if (oldCount > occurrences) {
    numberRemoved = occurrences;
  } else {
    numberRemoved = oldCount;
    backingMap.remove(element);
  }
  frequency.add(-numberRemoved);
  size -= numberRemoved;
  return oldCount;
}
 

@CanIgnoreReturnValue
@GuardedBy("this") boolean removeEntry(ReferenceEntry<K, V> entry, int hash) {
  int newCount = this.count - 1;
  AtomicReferenceArray<ReferenceEntry<K, V>> table = this.table;
  int index = hash & (table.length() - 1);
  ReferenceEntry<K, V> first = table.get(index);
  for (ReferenceEntry<K, V> e = first; e != null; e = e.getNext()) {
    if (e == entry) {
      ++modCount;
      ReferenceEntry<K, V> newFirst = removeFromChain(first, e);
      newCount = this.count - 1;
      table.set(index, newFirst);
      this.count = newCount; // write-volatile
      return true;
    }
  }
  return false;
}
 

/**
 * Invokes {@code future.}{@link Future#get(long, TimeUnit) get(timeout, unit)} uninterruptibly.
 *
 * <p>Similar methods:
 *
 * <ul>
 * <li>To retrieve a result from a {@code Future} that is already done, use
 *     {@link Futures#getDone Futures.getDone}.
 * <li>To treat {@link InterruptedException} uniformly with other exceptions, use
 *     {@link Futures#getChecked(Future, Class, long, TimeUnit) Futures.getChecked}.
 * <li>To get uninterruptibility and remove checked exceptions, use {@link Futures#getUnchecked}.
 * </ul>
 *
 * @throws ExecutionException if the computation threw an exception
 * @throws CancellationException if the computation was cancelled
 * @throws TimeoutException if the wait timed out
 */

@CanIgnoreReturnValue
@GwtIncompatible // TODO
public static <V> V getUninterruptibly(Future<V> future, long timeout, TimeUnit unit)
           throws ExecutionException, TimeoutException {
  boolean interrupted = false;
  try {
    long remainingNanos = unit.toNanos(timeout);
    long end = System.nanoTime() + remainingNanos;
    while (true) {
      try {
        // Future treats negative timeouts just like zero.
        return future.get(remainingNanos, NANOSECONDS);
      } catch (InterruptedException e) {
        interrupted = true;
        remainingNanos = end - System.nanoTime();
      }
    }
  } finally {
    if (interrupted) {
      Thread.currentThread().interrupt();
    }
  }
}
 

@CanIgnoreReturnValue
private Map<R, V> removeColumn(Object column) {
  Map<R, V> output = new LinkedHashMap<R, V>();
  Iterator<Entry<R, Map<C, V>>> iterator = backingMap.entrySet().iterator();
  while (iterator.hasNext()) {
    Entry<R, Map<C, V>> entry = iterator.next();
    V value = entry.getValue().remove(column);
    if (value != null) {
      output.put(entry.getKey(), value);
      if (entry.getValue().isEmpty()) {
        iterator.remove();
      }
    }
  }
  return output;
}
 

/**
 * Creates a <i>mutable</i> {@code ArrayList} instance containing the given
 * elements; a very thin shortcut for creating an empty list and then calling
 * {@link Iterators#addAll}.
 *
 * <p><b>Note:</b> if mutability is not required and the elements are
 * non-null, use {@link ImmutableList#copyOf(Iterator)} instead.
 */

@CanIgnoreReturnValue // TODO(kak): Remove this
@GwtCompatible(serializable = true)
public static <E> ArrayList<E> newArrayList(Iterator<? extends E> elements) {
  ArrayList<E> list = newArrayList();
  Iterators.addAll(list, elements);
  return list;
}
 

@CanIgnoreReturnValue
static Object checkElementNotNull(Object element, int index) {
  if (element == null) {
    throw new NullPointerException("at index " + index);
  }
  return element;
}
 

/**
 * Ensures that an object reference passed as a parameter to the calling method is not null.
 *
 * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
 */

@CanIgnoreReturnValue
public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) {
  if (obj == null) {
    throw new NullPointerException(format(errorMessageTemplate, p1, p2));
  }
  return obj;
}
 

@CanIgnoreReturnValue
@Override
public Builder<K, V> putAll(K key, Iterable<? extends V> values) {
  Collection<V> collection = builderMultimap.get(checkNotNull(key));
  for (V value : values) {
    collection.add(checkNotNull(value));
  }
  return this;
}
 

/**
 * Guaranteed to throw an exception and leave the collection unmodified.
 *
 * @throws UnsupportedOperationException always
 * @deprecated Unsupported operation.
 */

@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean addAll(Collection<? extends E> newElements) {
  throw new UnsupportedOperationException();
}
 

/**
 * Associates {@code key} with {@code value} in the built map. Duplicate
 * keys are not allowed, and will cause {@link #build} to fail.
 */

@CanIgnoreReturnValue
public Builder<K, V> put(K key, V value) {
  ensureCapacity(size + 1);
  ImmutableMapEntry<K, V> entry = entryOf(key, value);
  // don't inline this: we want to fail atomically if key or value is null
  entries[size++] = entry;
  return this;
}
 

/**
 * Guaranteed to throw an exception and leave the map unmodified.
 *
 * @throws UnsupportedOperationException always
 * @deprecated Unsupported operation.
 */

@CanIgnoreReturnValue
@Deprecated
@Override
public final V remove(Object o) {
  throw new UnsupportedOperationException();
}
 

/**
 * Guaranteed to throw an exception and leave the collection unmodified.
 *
 * @throws UnsupportedOperationException always
 * @deprecated Unsupported operation.
 */

@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean remove(Object object) {
  throw new UnsupportedOperationException();
}
 

/**
 * Removes the element at position {@code index}.
 *
 * <p>Normally this method leaves the elements at up to {@code index - 1},
 * inclusive, untouched.  Under these circumstances, it returns {@code null}.
 *
 * <p>Occasionally, in order to maintain the heap invariant, it must swap a
 * later element of the list with one before {@code index}. Under these
 * circumstances it returns a pair of elements as a {@link MoveDesc}. The
 * first one is the element that was previously at the end of the heap and is
 * now at some position before {@code index}. The second element is the one
 * that was swapped down to replace the element at {@code index}. This fact is
 * used by iterator.remove so as to visit elements during a traversal once and
 * only once.
 */

@VisibleForTesting
@CanIgnoreReturnValue
MoveDesc<E> removeAt(int index) {
  checkPositionIndex(index, size);
  modCount++;
  size--;
  if (size == index) {
    queue[size] = null;
    return null;
  }
  E actualLastElement = elementData(size);
  int lastElementAt = heapForIndex(size).getCorrectLastElement(actualLastElement);
  E toTrickle = elementData(size);
  queue[size] = null;
  MoveDesc<E> changes = fillHole(index, toTrickle);
  if (lastElementAt < index) {
    // Last element is moved to before index, swapped with trickled element.
    if (changes == null) {
      // The trickled element is still after index.
      return new MoveDesc<E>(actualLastElement, toTrickle);
    } else {
      // The trickled element is back before index, but the replaced element
      // has now been moved after index.
      return new MoveDesc<E>(actualLastElement, changes.replaced);
    }
  }
  // Trickled element was after index to begin with, no adjustment needed.
  return changes;
}
 

/**
 * Adds each element of {@code elements} to the {@code ImmutableSortedMultiset}.
 *
 * @param elements the elements to add
 * @return this {@code Builder} object
 * @throws NullPointerException if {@code elements} is null or contains a null element
 */

@CanIgnoreReturnValue
@Override
public Builder<E> add(E... elements) {
  super.add(elements);
  return this;
}
 

/**
 * {@inheritDoc}
 *
 * <p>This implementation is highly efficient when {@code elementsToAdd}
 * is itself a {@link Multiset}.
 */

@CanIgnoreReturnValue
@Override
public boolean addAll(Collection<? extends E> elementsToAdd) {
  return Multisets.addAllImpl(this, elementsToAdd);
}
 

@CanIgnoreReturnValue
@Override
public V put(K key, V value) {
  checkNotNull(key);
  checkNotNull(value);
  int hash = hash(key);
  return segmentFor(hash).put(key, hash, value, false);
}
 

/**
 * Removes every element that satisfies the provided predicate from the
 * iterator. The iterator will be left exhausted: its {@code hasNext()}
 * method will return {@code false}.
 *
 * @param removeFrom the iterator to (potentially) remove elements from
 * @param predicate a predicate that determines whether an element should
 *     be removed
 * @return {@code true} if any elements were removed from the iterator
 * @since 2.0
 */

@CanIgnoreReturnValue
public static <T> boolean removeIf(Iterator<T> removeFrom, Predicate<? super T> predicate) {
  checkNotNull(predicate);
  boolean modified = false;
  while (removeFrom.hasNext()) {
    if (predicate.apply(removeFrom.next())) {
      removeFrom.remove();
      modified = true;
    }
  }
  return modified;
}
 

@CanIgnoreReturnValue
@Override
public Node<K, V> next() {
  checkForConcurrentModification();
  checkElement(next);
  previous = current = next;
  next = next.next;
  nextIndex++;
  return current;
}
 

/**
 * Ensures that an object reference passed as a parameter to the calling method is not null.
 *
 * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
 */
@CanIgnoreReturnValue
public static <T> T checkNotNull(
    T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) {
  if (obj == null) {
    throw new NullPointerException(format(errorMessageTemplate, p1, p2));
  }
  return obj;
}
 

/**
 * Add a new mapping from an index to an object to the escaping.
 */

@CanIgnoreReturnValue
public CharEscaperBuilder addEscape(char c, String r) {
  map.put(c, checkNotNull(r));
  if (c > max) {
    max = c;
  }
  return this;
}
 

/**
 * {@inheritDoc}
 *
 * <p>If any entries for the specified {@code key} already exist in the
 * multimap, their values are changed in-place without affecting the iteration
 * order.
 *
 * <p>The returned list is immutable and implements
 * {@link java.util.RandomAccess}.
 */

@CanIgnoreReturnValue
@Override
public List<V> replaceValues(@Nullable K key, Iterable<? extends V> values) {
  List<V> oldValues = getCopy(key);
  ListIterator<V> keyValues = new ValueForKeyIterator(key);
  Iterator<? extends V> newValues = values.iterator();

  // Replace existing values, if any.
  while (keyValues.hasNext() && newValues.hasNext()) {
    keyValues.next();
    keyValues.set(newValues.next());
  }

  // Remove remaining old values, if any.

  while (keyValues.hasNext()) {
    keyValues.next();
    keyValues.remove();
  }

  // Add remaining new values, if any.

  while (newValues.hasNext()) {
    keyValues.add(newValues.next());
  }
  return oldValues;
}
 

/**
 * Removes a number of occurrences of the specified element from this multiset. If the multiset
 * contains fewer than this number of occurrences to begin with, all occurrences will be removed.
 *
 * @param element the element whose occurrences should be removed
 * @param occurrences the number of occurrences of the element to remove
 * @return the count of the element before the operation; possibly zero
 * @throws IllegalArgumentException if {@code occurrences} is negative
 */
/*
 * TODO(cpovirk): remove and removeExactly currently accept null inputs only
 * if occurrences == 0. This satisfies both NullPointerTester and
 * CollectionRemoveTester.testRemove_nullAllowed, but it's not clear that it's
 * a good policy, especially because, in order for the test to pass, the
 * parameter must be misleadingly annotated as @Nullable. I suspect that
 * we'll want to remove @Nullable, add an eager checkNotNull, and loosen up
 * testRemove_nullAllowed.
 */

@CanIgnoreReturnValue
@Override
public int remove(@Nullable Object element, int occurrences) {
  if (occurrences == 0) {
    return count(element);
  }
  CollectPreconditions.checkPositive(occurrences, "occurences");
  AtomicInteger existingCounter = Maps.safeGet(countMap, element);
  if (existingCounter == null) {
    return 0;
  }
  while (true) {
    int oldValue = existingCounter.get();
    if (oldValue != 0) {
      int newValue = Math.max(0, oldValue - occurrences);
      if (existingCounter.compareAndSet(oldValue, newValue)) {
        if (newValue == 0) {
          // Just CASed to 0; remove the entry to clean up the map. If the removal fails,
          // another thread has already replaced it with a new counter, which is fine.
          countMap.remove(element, existingCounter);
        }
        return oldValue;
      }
    } else {
      return 0;
    }
  }
}
 

@CanIgnoreReturnValue
@Override
public V next() {
  checkElement(next);
  previous = current = next;
  next = next.nextSibling;
  nextIndex++;
  return current.value;
}
 

/**
 * Add all ranges from the specified range set to this builder. Duplicate or connected ranges
 * are permitted, and will be merged in the resulting immutable range set.
 */

@CanIgnoreReturnValue
public Builder<C> addAll(RangeSet<C> ranges) {
  for (Range<C> range : ranges.asRanges()) {
    add(range);
  }
  return this;
}
 

/**
 * @since 15.0
 */

@CanIgnoreReturnValue
@Override
public final Service stopAsync() {
  delegate.stopAsync();
  return this;
}
 

/**
 * Ensures that an object reference passed as a parameter to the calling method is not null.
 *
 * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
 */

@CanIgnoreReturnValue
public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, @Nullable Object p1) {
  if (obj == null) {
    throw new NullPointerException(format(errorMessageTemplate, p1));
  }
  return obj;
}
 

/**
 * Add nodes that are not elements of the graph, then add {@code edge} between them.
 * Return {@code false} if {@code edge} already exists between {@code node1} and {@code node2},
 * and in the same direction.
 *
 * @throws IllegalArgumentException if an edge (other than {@code edge}) already
 *         exists from {@code node1} to {@code node2}, and this is not a multigraph.
 *         Also, if self-loops are not allowed, and {@code node1} is equal to {@code node2}.
 */

@Override
@CanIgnoreReturnValue
public boolean addEdge(E edge, N node1, N node2) {
  checkNotNull(edge, "edge");
  checkNotNull(node1, "node1");
  checkNotNull(node2, "node2");
  checkArgument(allowsSelfLoops() || !node1.equals(node2), SELF_LOOPS_NOT_ALLOWED, node1);
  boolean containsN1 = containsNode(node1);
  boolean containsN2 = containsNode(node2);
  if (containsEdge(edge)) {
    checkArgument(
      containsN1&& containsN2 && edgesConnecting(node1, node2).contains(edge),
      REUSING_EDGE,
      edge,
      incidentNodes(edge),
      node1,
      node2);
    return false;
  } else if (!allowsParallelEdges()) {
    checkArgument(
      !(containsN1 && containsN2 && successors(node1).contains(node2)),
      ADDING_PARALLEL_EDGE,
      node1,
      node2);
  }
  if (!containsN1) {
    addNode(node1);
  }
  NodeConnections<N, E> connectionsN1 = nodeConnections.get(node1);
  connectionsN1.addOutEdge(edge, node2);
  if (!containsN2) {
    addNode(node2);
  }
  NodeConnections<N, E> connectionsN2 = nodeConnections.get(node2);
  connectionsN2.addInEdge(edge, node1);
  edgeToReferenceNode.put(edge, node1);
  return true;
}
 

/**
 * Guaranteed to throw an exception and leave the bimap unmodified.
 *
 * @throws UnsupportedOperationException always
 * @deprecated Unsupported operation.
 */

@CanIgnoreReturnValue
@Deprecated
@Override
public V forcePut(K key, V value) {
  throw new UnsupportedOperationException();
}
 

/**
 * Adds each element of {@code elements} to the {@code ImmutableSortedMultiset}.
 *
 * @param elements the elements to add
 * @return this {@code Builder} object
 * @throws NullPointerException if {@code elements} is null or contains a null element
 */

@CanIgnoreReturnValue
@Override
public Builder<E> add(E... elements) {
  super.add(elements);
  return this;
}
 

/**
 * Adds all of the given entries to the built map.  Duplicate keys are not
 * allowed, and will cause {@link #build} to fail.
 *
 * @throws NullPointerException if any key, value, or entry is null
 * @since 19.0
 */

@CanIgnoreReturnValue
@Beta
public Builder<K, V> putAll(Iterable<? extends Entry<? extends K, ? extends V>> entries) {
  if (entries instanceof Collection) {
    ensureCapacity(size + ((Collection<?>) entries).size());
  }
  for (Entry<? extends K, ? extends V> entry : entries) {
    put(entry);
  }
  return this;
}