AtomicLongMap
Date: 2016-05-24

com.google.common.util.concurrent

## Class AtomicLongMap<K>

- java.lang.Object
- - com.google.common.util.concurrent.AtomicLongMap<K>

-     @GwtCompatible
      public final class AtomicLongMap<K>
      extends java.lang.Object

  A map containing `long` values that can be atomically updated. While writes to a traditional `Map` rely on `put(K, V)`, the typical mechanism for writing to this map is `addAndGet(K, long)`, which adds a `long` to the value currently associated with `K`. If a key has not yet been associated with a value, its implicit value is zero.

  Most methods in this class treat absent values and zero values identically, as individually documented. Exceptions to this are `containsKey(java.lang.Object)`, `size()`, `isEmpty()`, `asMap`, and `toString()`.

  Instances of this class may be used by multiple threads concurrently. All operations are atomic unless otherwise noted.

  Note: If your values are always positive and less than 2^31, you may wish to use a `Multiset` such as `ConcurrentHashMultiset` instead. Warning: Unlike `Multiset`, entries whose values are zero are not automatically removed from the map. Instead they must be removed manually with `removeAllZeros()`.

  Since:
    11.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `addAndGet(K key, long delta)` Adds `delta` to the value currently associated with `key`, and returns the new value.
    `java.util.Map<K,java.lang.Long>` | `asMap()` Returns a live, read-only view of the map backing this `AtomicLongMap`.
    `void` | `clear()` Removes all of the mappings from this map.
    `boolean` | `containsKey(java.lang.Object key)` Returns true if this map contains a mapping for the specified key.
    `static <K> AtomicLongMap<K>` | `create()` Creates an `AtomicLongMap`.
    `static <K> AtomicLongMap<K>` | `create(java.util.Map<? extends K,? extends java.lang.Long> m)` Creates an `AtomicLongMap` with the same mappings as the specified `Map`.
    `long` | `decrementAndGet(K key)` Decrements by one the value currently associated with `key`, and returns the new value.
    `long` | `get(K key)` Returns the value associated with `key`, or zero if there is no value associated with `key`.
    `long` | `getAndAdd(K key, long delta)` Adds `delta` to the value currently associated with `key`, and returns the old value.
    `long` | `getAndDecrement(K key)` Decrements by one the value currently associated with `key`, and returns the old value.
    `long` | `getAndIncrement(K key)` Increments by one the value currently associated with `key`, and returns the old value.
    `long` | `incrementAndGet(K key)` Increments by one the value currently associated with `key`, and returns the new value.
    `boolean` | `isEmpty()` Returns `true` if this map contains no key-value mappings.
    `long` | `put(K key, long newValue)` Associates `newValue` with `key` in this map, and returns the value previously associated with `key`, or zero if there was no such value.
    `void` | `putAll(java.util.Map<? extends K,? extends java.lang.Long> m)` Copies all of the mappings from the specified map to this map.
    `long` | `remove(K key)` Removes and returns the value associated with `key`.
    `void` | `removeAllZeros()` Removes all mappings from this map whose values are zero.
    `int` | `size()` Returns the number of key-value mappings in this map.
    `long` | `sum()` Returns the sum of all values in this map.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### create

          public static <K> AtomicLongMap<K> create()

      Creates an `AtomicLongMap`.

    - #### create

          public static <K> AtomicLongMap<K> create(java.util.Map<? extends K,? extends java.lang.Long> m)

      Creates an `AtomicLongMap` with the same mappings as the specified `Map`.

    - #### get

          public long get(K key)

      Returns the value associated with `key`, or zero if there is no value associated with `key`.

    - #### incrementAndGet

          public long incrementAndGet(K key)

      Increments by one the value currently associated with `key`, and returns the new value.

    - #### decrementAndGet

          public long decrementAndGet(K key)

      Decrements by one the value currently associated with `key`, and returns the new value.

    - #### addAndGet

          public long addAndGet(K key,
                       long delta)

      Adds `delta` to the value currently associated with `key`, and returns the new value.

    - #### getAndIncrement

          public long getAndIncrement(K key)

      Increments by one the value currently associated with `key`, and returns the old value.

    - #### getAndDecrement

          public long getAndDecrement(K key)

      Decrements by one the value currently associated with `key`, and returns the old value.

    - #### getAndAdd

          public long getAndAdd(K key,
                       long delta)

      Adds `delta` to the value currently associated with `key`, and returns the old value.

    - #### put

          public long put(K key,
                 long newValue)

      Associates `newValue` with `key` in this map, and returns the value previously associated with `key`, or zero if there was no such value.

    - #### putAll

          public void putAll(java.util.Map<? extends K,? extends java.lang.Long> m)

      Copies all of the mappings from the specified map to this map. The effect of this call is equivalent to that of calling `put(k, v)` on this map once for each mapping from key `k` to value `v` in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

    - #### remove

          public long remove(K key)

      Removes and returns the value associated with `key`. If `key` is not in the map, this method has no effect and returns zero.

    - #### removeAllZeros

          public void removeAllZeros()

      Removes all mappings from this map whose values are zero.

      This method is not atomic: the map may be visible in intermediate states, where some of the zero values have been removed and others have not.

    - #### sum

          public long sum()

      Returns the sum of all values in this map.

      This method is not atomic: the sum may or may not include other concurrent operations.

    - #### asMap

          public java.util.Map<K,java.lang.Long> asMap()

      Returns a live, read-only view of the map backing this `AtomicLongMap`.

    - #### containsKey

          public boolean containsKey(java.lang.Object key)

      Returns true if this map contains a mapping for the specified key.

    - #### size

          public int size()

      Returns the number of key-value mappings in this map. If the map contains more than `Integer.MAX_VALUE` elements, returns `Integer.MAX_VALUE`.

    - #### isEmpty

          public boolean isEmpty()

      Returns `true` if this map contains no key-value mappings.

    - #### clear

          public void clear()

      Removes all of the mappings from this map. The map will be empty after this call returns.

      This method is not atomic: the map may not be empty after returning if there were concurrent writes.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`