ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentHashMap.java
(Generate patch)

Comparing jsr166/src/main/java/util/concurrent/ConcurrentHashMap.java (file contents):
Revision 1.67 by jsr166, Thu May 12 23:57:21 2005 UTC vs.
Revision 1.68 by jsr166, Wed May 18 06:48:23 2005 UTC

# Line 33 | Line 33 | import java.io.ObjectOutputStream;
33   * removal of only some entries.  Similarly, Iterators and
34   * Enumerations return elements reflecting the state of the hash table
35   * at some point at or since the creation of the iterator/enumeration.
36 < * They do <em>not</em> throw
37 < * {@link ConcurrentModificationException}.  However, iterators are
38 < * designed to be used by only one thread at a time.
36 > * They do <em>not</em> throw {@link ConcurrentModificationException}.
37 > * However, iterators are designed to be used by only one thread at a time.
38   *
39   * <p> The allowed concurrency among update operations is guided by
40   * the optional <tt>concurrencyLevel</tt> constructor argument
# Line 59 | Line 58 | import java.io.ObjectOutputStream;
58   * <em>optional</em> methods of the {@link Map} and {@link Iterator}
59   * interfaces.
60   *
61 < * <p> Like {@link java.util.Hashtable} but unlike {@link
62 < * java.util.HashMap}, this class does NOT allow <tt>null</tt> to be
64 < * used as a key or value.
61 > * <p> Like {@link Hashtable} but unlike {@link HashMap}, this class
62 > * does <em>not</em> allow <tt>null</tt> to be used as a key or value.
63   *
64   * <p>This class is a member of the
65   * <a href="{@docRoot}/../guide/collections/index.html">
# Line 104 | Line 102 | public class ConcurrentHashMap<K, V> ext
102      /**
103       * The maximum capacity, used if a higher value is implicitly
104       * specified by either of the constructors with arguments.  MUST
105 <     * be a power of two <= 1<<30 to ensure that entries are indexible
105 >     * be a power of two <= 1<<30 to ensure that entries are indexable
106       * using ints.
107       */
108      static final int MAXIMUM_CAPACITY = 1 << 30;
# Line 261 | Line 259 | public class ConcurrentHashMap<K, V> ext
259  
260          /**
261           * The table is rehashed when its size exceeds this threshold.
262 <         * (The value of this field is always (int)(capacity *
263 <         * loadFactor).)
262 >         * (The value of this field is always <tt>(int)(capacity *
263 >         * loadFactor)</tt>.)
264           */
265          transient int threshold;
266  
# Line 612 | Line 610 | public class ConcurrentHashMap<K, V> ext
610       * @param initialCapacity The implementation performs internal
611       * sizing to accommodate this many elements.
612       * @param loadFactor  the load factor threshold, used to control resizing.
613 +     * Resizing may be performed when the average number of elements per
614 +     * bin exceeds this threshold.
615       * @throws IllegalArgumentException if the initial capacity of
616       * elements is negative or the load factor is nonpositive
617       */
# Line 650 | Line 650 | public class ConcurrentHashMap<K, V> ext
650       * (whichever is greater), and a default load factor
651       * (<tt>0.75f</tt>) and concurrencyLevel
652       * (<tt>16</tt>).
653 <     * @param t the map
653 >     * @param m the map
654       */
655 <    public ConcurrentHashMap(Map<? extends K, ? extends V> t) {
656 <        this(Math.max((int) (t.size() / DEFAULT_LOAD_FACTOR) + 1,
655 >    public ConcurrentHashMap(Map<? extends K, ? extends V> m) {
656 >        this(Math.max((int) (m.size() / DEFAULT_LOAD_FACTOR) + 1,
657                        DEFAULT_INITIAL_CAPACITY),
658               DEFAULT_LOAD_FACTOR, DEFAULT_CONCURRENCY_LEVEL);
659 <        putAll(t);
659 >        putAll(m);
660      }
661  
662      /**
663       * Returns <tt>true</tt> if this map contains no key-value mappings.
664       *
665 <     * @return <tt>true</tt> if this map contains no key-value mappings.
665 >     * @return <tt>true</tt> if this map contains no key-value mappings
666       */
667      public boolean isEmpty() {
668          final Segment[] segments = this.segments;
# Line 701 | Line 701 | public class ConcurrentHashMap<K, V> ext
701       * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
702       * <tt>Integer.MAX_VALUE</tt>.
703       *
704 <     * @return the number of key-value mappings in this map.
704 >     * @return the number of key-value mappings in this map
705       */
706      public int size() {
707          final Segment[] segments = this.segments;
# Line 745 | Line 745 | public class ConcurrentHashMap<K, V> ext
745              return (int)sum;
746      }
747  
748 –
748      /**
749 <     * Returns the value to which the specified key is mapped in this table.
749 >     * Returns the value to which this map maps the specified key, or
750 >     * <tt>null</tt> if the map contains no mapping for the key.
751       *
752 <     * @param   key   a key in the table.
753 <     * @return  the value to which the key is mapped in this table;
754 <     *          <tt>null</tt> if the key is not mapped to any value in
755 <     *          this table.
756 <     * @throws  NullPointerException  if the key is
757 <     *               <tt>null</tt>.
752 >     * @param key key whose associated value is to be returned
753 >     * @return the value associated with <tt>key</tt> in this map, or
754 >     *         <tt>null</tt> if there is no mapping for <tt>key</tt>
755 >     * @throws NullPointerException if the specified key is null
756       */
757      public V get(Object key) {
758          int hash = hash(key); // throws NullPointerException if key null
# Line 764 | Line 762 | public class ConcurrentHashMap<K, V> ext
762      /**
763       * Tests if the specified object is a key in this table.
764       *
765 <     * @param   key   possible key.
766 <     * @return  <tt>true</tt> if and only if the specified object
767 <     *          is a key in this table, as determined by the
768 <     *          <tt>equals</tt> method; <tt>false</tt> otherwise.
769 <     * @throws  NullPointerException  if the key is
772 <     *               <tt>null</tt>.
765 >     * @param  key   possible key
766 >     * @return <tt>true</tt> if and only if the specified object
767 >     *         is a key in this table, as determined by the
768 >     *         <tt>equals</tt> method; <tt>false</tt> otherwise.
769 >     * @throws NullPointerException if the specified key is null
770       */
771      public boolean containsKey(Object key) {
772          int hash = hash(key); // throws NullPointerException if key null
# Line 782 | Line 779 | public class ConcurrentHashMap<K, V> ext
779       * traversal of the hash table, and so is much slower than
780       * method <tt>containsKey</tt>.
781       *
782 <     * @param value value whose presence in this map is to be tested.
782 >     * @param value value whose presence in this map is to be tested
783       * @return <tt>true</tt> if this map maps one or more keys to the
784 <     * specified value.
785 <     * @throws  NullPointerException  if the value is <tt>null</tt>.
784 >     *         specified value
785 >     * @throws NullPointerException if the specified value is null
786       */
787      public boolean containsValue(Object value) {
788          if (value == null)
# Line 840 | Line 837 | public class ConcurrentHashMap<K, V> ext
837      /**
838       * Legacy method testing if some key maps into the specified value
839       * in this table.  This method is identical in functionality to
840 <     * {@link #containsValue}, and  exists solely to ensure
840 >     * {@link #containsValue}, and exists solely to ensure
841       * full compatibility with class {@link java.util.Hashtable},
842       * which supported this method prior to introduction of the
843       * Java Collections framework.
844  
845 <     * @param      value   a value to search for.
846 <     * @return     <tt>true</tt> if and only if some key maps to the
847 <     *             <tt>value</tt> argument in this table as
848 <     *             determined by the <tt>equals</tt> method;
849 <     *             <tt>false</tt> otherwise.
850 <     * @throws  NullPointerException  if the value is <tt>null</tt>.
845 >     * @param  value a value to search for
846 >     * @return <tt>true</tt> if and only if some key maps to the
847 >     *         <tt>value</tt> argument in this table as
848 >     *         determined by the <tt>equals</tt> method;
849 >     *         <tt>false</tt> otherwise
850 >     * @throws NullPointerException if the specified value is null
851       */
852      public boolean contains(Object value) {
853          return containsValue(value);
# Line 864 | Line 861 | public class ConcurrentHashMap<K, V> ext
861       * <p> The value can be retrieved by calling the <tt>get</tt> method
862       * with a key that is equal to the original key.
863       *
864 <     * @param      key     the table key.
865 <     * @param      value   the value.
866 <     * @return     the previous value of the specified key in this table,
867 <     *             or <tt>null</tt> if it did not have one.
868 <     * @throws  NullPointerException  if the key or value is
872 <     *               <tt>null</tt>.
864 >     * @param key key with which the specified value is to be associated
865 >     * @param value value to be associated with the specified key
866 >     * @return the previous value associated with <tt>key</tt>, or
867 >     *         <tt>null</tt> if there was no mapping for <tt>key</tt>
868 >     * @throws NullPointerException if the specified key or value is null
869       */
870      public V put(K key, V value) {
871          if (value == null)
# Line 879 | Line 875 | public class ConcurrentHashMap<K, V> ext
875      }
876  
877      /**
878 <     * If the specified key is not already associated
879 <     * with a value, associate it with the given value.
880 <     * This is equivalent to
881 <     * <pre>
882 <     *   if (!map.containsKey(key))
887 <     *      return map.put(key, value);
888 <     *   else
889 <     *      return map.get(key);</pre>
890 <     * except that the action is performed atomically.
891 <     * @param key key with which the specified value is to be associated.
892 <     * @param value value to be associated with the specified key.
893 <     * @return previous value associated with specified key, or <tt>null</tt>
894 <     *         if there was no mapping for key.
895 <     * @throws NullPointerException if the specified key or value is
896 <     *            <tt>null</tt>.
878 >     * {@inheritDoc}
879 >     *
880 >     * @return the previous value associated with the specified key,
881 >     *         or <tt>null</tt> if there was no mapping for the key
882 >     * @throws NullPointerException if the specified key or value is null
883       */
884      public V putIfAbsent(K key, V value) {
885          if (value == null)
# Line 902 | Line 888 | public class ConcurrentHashMap<K, V> ext
888          return segmentFor(hash).put(key, hash, value, true);
889      }
890  
905 –
891      /**
892       * Copies all of the mappings from the specified map to this one.
908 –     *
893       * These mappings replace any mappings that this map had for any of the
894 <     * keys currently in the specified Map.
894 >     * keys currently in the specified map.
895       *
896 <     * @param t Mappings to be stored in this map.
896 >     * @param m mappings to be stored in this map
897       */
898 <    public void putAll(Map<? extends K, ? extends V> t) {
899 <        for (Iterator<? extends Map.Entry<? extends K, ? extends V>> it = (Iterator<? extends Map.Entry<? extends K, ? extends V>>) t.entrySet().iterator(); it.hasNext(); ) {
898 >    public void putAll(Map<? extends K, ? extends V> m) {
899 >        for (Iterator<? extends Map.Entry<? extends K, ? extends V>> it = (Iterator<? extends Map.Entry<? extends K, ? extends V>>) m.entrySet().iterator(); it.hasNext(); ) {
900              Entry<? extends K, ? extends V> e = it.next();
901              put(e.getKey(), e.getValue());
902          }
903      }
904  
905      /**
906 <     * Removes the key (and its corresponding value) from this
907 <     * table. This method does nothing if the key is not in the table.
906 >     * Removes the key (and its corresponding value) from this map.
907 >     * This method does nothing if the key is not in the map.
908       *
909 <     * @param   key   the key that needs to be removed.
910 <     * @return  the value to which the key had been mapped in this table,
911 <     *          or <tt>null</tt> if the key did not have a mapping.
912 <     * @throws  NullPointerException  if the key is
929 <     *               <tt>null</tt>.
909 >     * @param  key the key that needs to be removed
910 >     * @return the previous value associated with <tt>key</tt>, or
911 >     *         <tt>null</tt> if there was no mapping for <tt>key</tt>.
912 >     * @throws NullPointerException if the specified key is null
913       */
914      public V remove(Object key) {
915          int hash = hash(key);
# Line 934 | Line 917 | public class ConcurrentHashMap<K, V> ext
917      }
918  
919      /**
920 <     * Remove entry for key only if currently mapped to given value.
921 <     * This is equivalent to
922 <     * <pre>
940 <     *  if (map.containsKey(key) && map.get(key).equals(value)) {
941 <     *     map.remove(key);
942 <     *     return true;
943 <     * } else return false;</pre>
944 <     * except that the action is performed atomically.
945 <     * @param key key with which the specified value is associated.
946 <     * @param value value associated with the specified key.
947 <     * @return true if the value was removed
948 <     * @throws NullPointerException if the specified key is
949 <     *            <tt>null</tt>.
920 >     * {@inheritDoc}
921 >     *
922 >     * @throws NullPointerException if the specified key or value is null
923       */
924      public boolean remove(Object key, Object value) {
925 +        if (value == null)
926 +            throw new NullPointerException();
927          int hash = hash(key);
928          return segmentFor(hash).remove(key, hash, value) != null;
929      }
930  
956 –
931      /**
932 <     * Replaces entry for key only if currently mapped to given value.
933 <     * This is equivalent to
934 <     * <pre>
961 <     *  if (map.containsKey(key) && map.get(key).equals(oldValue)) {
962 <     *     map.put(key, newValue);
963 <     *     return true;
964 <     * } else return false;</pre>
965 <     * except that the action is performed atomically.
966 <     * @param key key with which the specified value is associated.
967 <     * @param oldValue value expected to be associated with the specified key.
968 <     * @param newValue value to be associated with the specified key.
969 <     * @return true if the value was replaced
970 <     * @throws NullPointerException if the specified key or values are
971 <     * <tt>null</tt>.
932 >     * {@inheritDoc}
933 >     *
934 >     * @throws NullPointerException if any of the arguments are null
935       */
936      public boolean replace(K key, V oldValue, V newValue) {
937          if (oldValue == null || newValue == null)
# Line 978 | Line 941 | public class ConcurrentHashMap<K, V> ext
941      }
942  
943      /**
944 <     * Replaces entry for key only if currently mapped to some value.
945 <     * This is equivalent to
946 <     * <pre>
947 <     *  if (map.containsKey(key)) {
948 <     *     return map.put(key, value);
986 <     * } else return null;</pre>
987 <     * except that the action is performed atomically.
988 <     * @param key key with which the specified value is associated.
989 <     * @param value value to be associated with the specified key.
990 <     * @return previous value associated with specified key, or <tt>null</tt>
991 <     *         if there was no mapping for key.
992 <     * @throws NullPointerException if the specified key or value is
993 <     *            <tt>null</tt>.
944 >     * {@inheritDoc}
945 >     *
946 >     * @return the previous value associated with the specified key,
947 >     *         or <tt>null</tt> if there was no mapping for the key
948 >     * @throws NullPointerException if the specified key or value is null
949       */
950      public V replace(K key, V value) {
951          if (value == null)
# Line 999 | Line 954 | public class ConcurrentHashMap<K, V> ext
954          return segmentFor(hash).replace(key, hash, value);
955      }
956  
1002 –
957      /**
958 <     * Removes all mappings from this map.
958 >     * Removes all of the mappings from this map.
959       */
960      public void clear() {
961          for (int i = 0; i < segments.length; ++i)
# Line 1009 | Line 963 | public class ConcurrentHashMap<K, V> ext
963      }
964  
965      /**
966 <     * Returns a set view of the keys contained in this map.  The set is
967 <     * backed by the map, so changes to the map are reflected in the set, and
968 <     * vice-versa.  The set supports element removal, which removes the
969 <     * corresponding mapping from this map, via the <tt>Iterator.remove</tt>,
970 <     * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt>, and
971 <     * <tt>clear</tt> operations.  It does not support the <tt>add</tt> or
966 >     * Returns a {@link Set} view of the keys contained in this map.
967 >     * The set is backed by the map, so changes to the map are
968 >     * reflected in the set, and vice-versa.  The set supports element
969 >     * removal, which removes the corresponding mapping from this map,
970 >     * via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
971 >     * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
972 >     * operations.  It does not support the <tt>add</tt> or
973       * <tt>addAll</tt> operations.
974 <     * The view's returned <tt>iterator</tt> is a "weakly consistent" iterator that
975 <     * will never throw {@link java.util.ConcurrentModificationException},
974 >     *
975 >     * <p>The view's <tt>iterator</tt> is a "weakly consistent" iterator
976 >     * that will never throw {@link ConcurrentModificationException},
977       * and guarantees to traverse elements as they existed upon
978       * construction of the iterator, and may (but is not guaranteed to)
979       * reflect any modifications subsequent to construction.
1024 –     *
1025 –     * @return a set view of the keys contained in this map.
980       */
981      public Set<K> keySet() {
982          Set<K> ks = keySet;
983          return (ks != null) ? ks : (keySet = new KeySet());
984      }
985  
1032 –
986      /**
987 <     * Returns a collection view of the values contained in this map.  The
988 <     * collection is backed by the map, so changes to the map are reflected in
989 <     * the collection, and vice-versa.  The collection supports element
990 <     * removal, which removes the corresponding mapping from this map, via the
991 <     * <tt>Iterator.remove</tt>, <tt>Collection.remove</tt>,
992 <     * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt> operations.
993 <     * It does not support the <tt>add</tt> or <tt>addAll</tt> operations.
994 <     * The view's returned <tt>iterator</tt> is a "weakly consistent" iterator that
995 <     * will never throw {@link java.util.ConcurrentModificationException},
987 >     * Returns a {@link Collection} view of the values contained in this map.
988 >     * The collection is backed by the map, so changes to the map are
989 >     * reflected in the collection, and vice-versa.  The collection
990 >     * supports element removal, which removes the corresponding
991 >     * mapping from this map, via the <tt>Iterator.remove</tt>,
992 >     * <tt>Collection.remove</tt>, <tt>removeAll</tt>,
993 >     * <tt>retainAll</tt>, and <tt>clear</tt> operations.  It does not
994 >     * support the <tt>add</tt> or <tt>addAll</tt> operations.
995 >     *
996 >     * <p>The view's <tt>iterator</tt> is a "weakly consistent" iterator
997 >     * that will never throw {@link ConcurrentModificationException},
998       * and guarantees to traverse elements as they existed upon
999       * construction of the iterator, and may (but is not guaranteed to)
1000       * reflect any modifications subsequent to construction.
1046 –     *
1047 –     * @return a collection view of the values contained in this map.
1001       */
1002      public Collection<V> values() {
1003          Collection<V> vs = values;
1004          return (vs != null) ? vs : (values = new Values());
1005      }
1006  
1054 –
1007      /**
1008 <     * Returns a collection view of the mappings contained in this map.  Each
1009 <     * element in the returned collection is a <tt>Map.Entry</tt>.  The
1010 <     * collection is backed by the map, so changes to the map are reflected in
1011 <     * the collection, and vice-versa.  The collection supports element
1012 <     * removal, which removes the corresponding mapping from the map, via the
1013 <     * <tt>Iterator.remove</tt>, <tt>Collection.remove</tt>,
1014 <     * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt> operations.
1015 <     * It does not support the <tt>add</tt> or <tt>addAll</tt> operations.
1016 <     * The view's returned <tt>iterator</tt> is a "weakly consistent" iterator that
1017 <     * will never throw {@link java.util.ConcurrentModificationException},
1008 >     * Returns a {@link Set} view of the mappings contained in this map.
1009 >     * The set is backed by the map, so changes to the map are
1010 >     * reflected in the set, and vice-versa.  The set supports element
1011 >     * removal, which removes the corresponding mapping from the map,
1012 >     * via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
1013 >     * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
1014 >     * operations.  It does not support the <tt>add</tt> or
1015 >     * <tt>addAll</tt> operations.
1016 >     *
1017 >     * <p>The view's <tt>iterator</tt> is a "weakly consistent" iterator
1018 >     * that will never throw {@link ConcurrentModificationException},
1019       * and guarantees to traverse elements as they existed upon
1020       * construction of the iterator, and may (but is not guaranteed to)
1021       * reflect any modifications subsequent to construction.
1069 –     *
1070 –     * @return a collection view of the mappings contained in this map.
1022       */
1023      public Set<Map.Entry<K,V>> entrySet() {
1024          Set<Map.Entry<K,V>> es = entrySet;
1025          return (es != null) ? es : (entrySet = new EntrySet());
1026      }
1027  
1077 –
1028      /**
1029       * Returns an enumeration of the keys in this table.
1030       *
1031 <     * @return  an enumeration of the keys in this table.
1031 >     * @return  an enumeration of the keys in this table
1032       * @see     #keySet
1033       */
1034      public Enumeration<K> keys() {
# Line 1088 | Line 1038 | public class ConcurrentHashMap<K, V> ext
1038      /**
1039       * Returns an enumeration of the values in this table.
1040       *
1041 <     * @return  an enumeration of the values in this table.
1041 >     * @return  an enumeration of the values in this table
1042       * @see     #values
1043       */
1044      public Enumeration<V> elements() {
# Line 1330 | Line 1280 | public class ConcurrentHashMap<K, V> ext
1280      /* ---------------- Serialization Support -------------- */
1281  
1282      /**
1283 <     * Save the state of the <tt>ConcurrentHashMap</tt>
1284 <     * instance to a stream (i.e.,
1335 <     * serialize it).
1283 >     * Save the state of the <tt>ConcurrentHashMap</tt> instance to a
1284 >     * stream (i.e., serialize it).
1285       * @param s the stream
1286       * @serialData
1287       * the key (Object) and value (Object)
# Line 1362 | Line 1311 | public class ConcurrentHashMap<K, V> ext
1311      }
1312  
1313      /**
1314 <     * Reconstitute the <tt>ConcurrentHashMap</tt>
1315 <     * instance from a stream (i.e.,
1367 <     * deserialize it).
1314 >     * Reconstitute the <tt>ConcurrentHashMap</tt> instance from a
1315 >     * stream (i.e., deserialize it).
1316       * @param s the stream
1317       */
1318      private void readObject(java.io.ObjectInputStream s)
# Line 1386 | Line 1334 | public class ConcurrentHashMap<K, V> ext
1334          }
1335      }
1336   }
1389 –

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines