src/jdk.internal.vm.compiler/share/classes/jdk.internal.vm.compiler.word/src/jdk/internal/vm/compiler/word/Pointer.java

rev 52509 : [mq]: graal2

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.

@@ -20,10 +20,26 @@
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 package jdk.internal.vm.compiler.word;
 
 /**
  * Lowest-level memory access of native C memory.
  * <p>

@@ -957,149 +973,161 @@
      * @since 1.0
      */
     void writeObject(WordBase offset, Object val);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     int compareAndSwapInt(WordBase offset, int expectedValue, int newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     long compareAndSwapLong(WordBase offset, long expectedValue, long newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     <T extends WordBase> T compareAndSwapWord(WordBase offset, T expectedValue, T newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     Object compareAndSwapObject(WordBase offset, Object expectedValue, Object newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0
      */
     boolean logicCompareAndSwapInt(WordBase offset, int expectedValue, int newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0
      */
     boolean logicCompareAndSwapLong(WordBase offset, long expectedValue, long newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0
      */
     boolean logicCompareAndSwapWord(WordBase offset, WordBase expectedValue, WordBase newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      * <p>
      * The offset is always treated as a {@link SignedWord} value. However, the static type is
      * {@link WordBase} to avoid the frequent casts of {@link UnsignedWord} values (where the caller
      * knows that the highest-order bit of the unsigned value is never used).
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0

@@ -1204,117 +1232,129 @@
      * @since 1.0
      */
     void writeObject(int offset, Object val);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     int compareAndSwapInt(int offset, int expectedValue, int newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     long compareAndSwapLong(int offset, long expectedValue, long newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     <T extends WordBase> T compareAndSwapWord(int offset, T expectedValue, T newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
-     * @return The value after the atomic exchange
+     * @return The value that was read for comparison, which is {@code expectedValue} if the
+     *         exchange was performed.
      *
      * @since 1.0
      */
     Object compareAndSwapObject(int offset, Object expectedValue, Object newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0
      */
     boolean logicCompareAndSwapInt(int offset, int expectedValue, int newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0
      */
     boolean logicCompareAndSwapLong(int offset, long expectedValue, long newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0
      */
     boolean logicCompareAndSwapWord(int offset, WordBase expectedValue, WordBase newValue, LocationIdentity locationIdentity);
 
     /**
-     * Atomically exchanges memory at address {@code (this + offset)}. Both the base address and
+     * In a single atomic step, compares the memory at address {@code (this + offset)} to the
+     * expected value, and if equal, exchanges it for the new value. Both the base address and
      * offset are in bytes.
      *
      * @param offset the signed offset for the memory access
-     * @param expectedValue the expected value of the atomic exchange
-     * @param newValue the new value of the atomic exchange
+     * @param expectedValue the expected current value at the memory address
+     * @param newValue the new value for the atomic exchange
      * @param locationIdentity the identity of the memory location
      * @return {@code true} if successful. False return indicates that the actual value was not
      *         equal to the expected value.
      *
      * @since 1.0