package sun.misc;
import java.lang.reflect.Field;
/***
 * This class should provide access to low-level operations and its
 * use should be limited to trusted code.  Fields can be accessed using
 * memory addresses, with undefined behaviour occurring if invalid memory
 * addresses are given.
 * 這個類提供了一個更底層的操作並且應該在受信任的程式碼中使用。可以通過記憶體地址
 * 存取fields,如果給出的記憶體地址是無效的那麼會有一個不確定的執行表現。
 * 
 * @author Tom Tromey (
 
[email protected])
 * @author Andrew John Hughes ([email protected])
 */
public class Unsafe
{
  // Singleton class.
  private static Unsafe unsafe = new Unsafe();
  /***
   * Private default constructor to prevent creation of an arbitrary
   * number of instances.
   * 使用私有預設構造器防止建立多個例項
   */
  private Unsafe()
  {
  }
  /***
   * Retrieve the singleton instance of <code>Unsafe</code>.  The calling
   * method should guard this instance from untrusted code, as it provides
   * access to low-level operations such as direct memory access.
   * 獲取<code>Unsafe</code>的單例,這個方法呼叫應該防止在不可信的程式碼中例項，
   * 因為unsafe類提供了一個低級別的操作，例如直接記憶體存取。
   * 
   * @throws SecurityException if a security manager exists and prevents
   *                           access to the system properties.
   *                           如果安全管理器不存在或者禁止訪問系統屬性
   */
  public static Unsafe getUnsafe()
  {
    SecurityManager sm = System.getSecurityManager();
    if (sm != null)
      sm.checkPropertiesAccess();
    return unsafe;
  }
  
  /***
   * Returns the memory address offset of the given static field.
   * The offset is merely used as a means to access a particular field
   * in the other methods of this class.  The value is unique to the given
   * field and the same value should be returned on each subsequent call.
   * 返回指定靜態field的記憶體地址偏移量,在這個類的其他方法中這個值只是被用作一個訪問
   * 特定field的一個方式。這個值對於 給定的field是唯一的，並且後續對該方法的呼叫都應該
   * 返回相同的值。
   *
   * @param field the field whose offset should be returned.
   *              需要返回偏移量的field
   * @return the offset of the given field.
   *         指定field的偏移量
   */
  public native long objectFieldOffset(Field field);
  /***
   * Compares the value of the integer field at the specified offset
   * in the supplied object with the given expected value, and updates
   * it if they match.  The operation of this method should be atomic,
   * thus providing an uninterruptible way of updating an integer field.
   * 在obj的offset位置比較integer field和期望的值，如果相同則更新。這個方法
   * 的操作應該是原子的，因此提供了一種不可中斷的方式更新integer field。
   * 
   * @param obj the object containing the field to modify.
   *            包含要修改field的物件
   * @param offset the offset of the integer field within <code>obj</code>.
   *               <code>obj</code>中整型field的偏移量
   * @param expect the expected value of the field.
   *               希望field中存在的值
   * @param update the new value of the field if it equals <code>expect</code>.
   *           如果期望值expect與field的當前值相同，設定filed的值為這個新值
   * @return true if the field was changed.
   *                             如果field的值被更改
   */
  public native boolean compareAndSwapInt(Object obj, long offset,
                                          int expect, int update);
  /***
   * Compares the value of the long field at the specified offset
   * in the supplied object with the given expected value, and updates
   * it if they match.  The operation of this method should be atomic,
   * thus providing an uninterruptible way of updating a long field.
   * 在obj的offset位置比較long field和期望的值，如果相同則更新。這個方法
   * 的操作應該是原子的，因此提供了一種不可中斷的方式更新long field。
   * 
   * @param obj the object containing the field to modify.
   *              包含要修改field的物件 
   * @param offset the offset of the long field within <code>obj</code>.
   *               <code>obj</code>中long型field的偏移量
   * @param expect the expected value of the field.
   *               希望field中存在的值
   * @param update the new value of the field if it equals <code>expect</code>.
   *               如果期望值expect與field的當前值相同，設定filed的值為這個新值
   * @return true if the field was changed.
   *              如果field的值被更改
   */
  public native boolean compareAndSwapLong(Object obj, long offset,
                                           long expect, long update);
  /***
   * Compares the value of the object field at the specified offset
   * in the supplied object with the given expected value, and updates
   * it if they match.  The operation of this method should be atomic,
   * thus providing an uninterruptible way of updating an object field.
   * 在obj的offset位置比較object field和期望的值，如果相同則更新。這個方法
   * 的操作應該是原子的，因此提供了一種不可中斷的方式更新object field。
   * 
   * @param obj the object containing the field to modify.
   *    包含要修改field的物件 
   * @param offset the offset of the object field within <code>obj</code>.
   *         <code>obj</code>中object型field的偏移量
   * @param expect the expected value of the field.
   *               希望field中存在的值
   * @param update the new value of the field if it equals <code>expect</code>.
   *               如果期望值expect與field的當前值相同，設定filed的值為這個新值
   * @return true if the field was changed.
   *              如果field的值被更改
   */
  public native boolean compareAndSwapObject(Object obj, long offset,
                                             Object expect, Object update);
  /***
   * Sets the value of the integer field at the specified offset in the
   * supplied object to the given value.  This is an ordered or lazy
   * version of <code>putIntVolatile(Object,long,int)</code>, which
   * doesn't guarantee the immediate visibility of the change to other
   * threads.  It is only really useful where the integer field is
   * <code>volatile</code>, and is thus expected to change unexpectedly.
   * 設定obj物件中offset偏移地址對應的整型field的值為指定值。這是一個有序或者
   * 有延遲的<code>putIntVolatile</cdoe>方法，並且不保證值的改變被其他執行緒立
   * 即看到。只有在field被<code>volatile</code>修飾並且期望被意外修改的時候
   * 使用才有用。
   * 
   * @param obj the object containing the field to modify.
   *    包含需要修改field的物件
   * @param offset the offset of the integer field within <code>obj</code>.
   *       <code>obj</code>中整型field的偏移量
   * @param value the new value of the field.
   *      field將被設定的新值
   * @see #putIntVolatile(Object,long,int)
   */
  public native void putOrderedInt(Object obj, long offset, int value);
  /***
   * Sets the value of the long field at the specified offset in the
   * supplied object to the given value.  This is an ordered or lazy
   * version of <code>putLongVolatile(Object,long,long)</code>, which
   * doesn't guarantee the immediate visibility of the change to other
   * threads.  It is only really useful where the long field is
   * <code>volatile</code>, and is thus expected to change unexpectedly.
   * 設定obj物件中offset偏移地址對應的long型field的值為指定值。這是一個有序或者
   * 有延遲的<code>putLongVolatile</cdoe>方法，並且不保證值的改變被其他執行緒立
   * 即看到。只有在field被<code>volatile</code>修飾並且期望被意外修改的時候
   * 使用才有用。
   * 
   * @param obj the object containing the field to modify.
   *    包含需要修改field的物件
   * @param offset the offset of the long field within <code>obj</code>.
   *       <code>obj</code>中long型field的偏移量
   * @param value the new value of the field.
   *      field將被設定的新值
   * @see #putLongVolatile(Object,long,long)
   */
  public native void putOrderedLong(Object obj, long offset, long value);
  /***
   * Sets the value of the object field at the specified offset in the
   * supplied object to the given value.  This is an ordered or lazy
   * version of <code>putObjectVolatile(Object,long,Object)</code>, which
   * doesn't guarantee the immediate visibility of the change to other
   * threads.  It is only really useful where the object field is
   * <code>volatile</code>, and is thus expected to change unexpectedly.
   * 設定obj物件中offset偏移地址對應的object型field的值為指定值。這是一個有序或者
   * 有延遲的<code>putObjectVolatile</cdoe>方法，並且不保證值的改變被其他執行緒立
   * 即看到。只有在field被<code>volatile</code>修飾並且期望被意外修改的時候
   * 使用才有用。
   *
   * @param obj the object containing the field to modify.
   *    包含需要修改field的物件
   * @param offset the offset of the object field within <code>obj</code>.
   *       <code>obj</code>中long型field的偏移量
   * @param value the new value of the field.
   *      field將被設定的新值
   */
  public native void putOrderedObject(Object obj, long offset, Object value);
  /***
   * Sets the value of the integer field at the specified offset in the
   * supplied object to the given value, with volatile store semantics.
   * 設定obj物件中offset偏移地址對應的整型field的值為指定值。支援volatile store語義
   * 
   * @param obj the object containing the field to modify.
   *    包含需要修改field的物件
   * @param offset the offset of the integer field within <code>obj</code>.
   *       <code>obj</code>中整型field的偏移量
   * @param value the new value of the field.
   *       field將被設定的新值
   */
  public native void putIntVolatile(Object obj, long offset, int value);
  /***
   * Retrieves the value of the integer field at the specified offset in the
   * supplied object with volatile load semantics.
   * 獲取obj物件中offset偏移地址對應的整型field的值,支援volatile load語義。
   * 
   * @param obj the object containing the field to read.
   *    包含需要去讀取的field的物件
   * @param offset the offset of the integer field within <code>obj</code>.
   *       <code>obj</code>中整型field的偏移量
   */
  public native int getIntVolatile(Object obj, long offset);
  /***
   * Sets the value of the long field at the specified offset in the
   * supplied object to the given value, with volatile store semantics.
   * 設定obj物件中offset偏移地址對應的long型field的值為指定值。支援volatile store語義
   *
   * @param obj the object containing the field to modify.
   *            包含需要修改field的物件
   * @param offset the offset of the long field within <code>obj</code>.
   *               <code>obj</code>中long型field的偏移量
   * @param value the new value of the field.
   *              field將被設定的新值
   * @see #putLong(Object,long,long)
   */
  public native void putLongVolatile(Object obj, long offset, long value);
  /***
   * Sets the value of the long field at the specified offset in the
   * supplied object to the given value.
   * 設定obj物件中offset偏移地址對應的long型field的值為指定值。
   * 
   * @param obj the object containing the field to modify.
   *     包含需要修改field的物件
   * @param offset the offset of the long field within <code>obj</code>.
   *     <code>obj</code>中long型field的偏移量
   * @param value the new value of the field.
   *     field將被設定的新值
   * @see #putLongVolatile(Object,long,long)
   */
  public native void putLong(Object obj, long offset, long value);
  /***
   * Retrieves the value of the long field at the specified offset in the
   * supplied object with volatile load semantics.
   * 獲取obj物件中offset偏移地址對應的long型field的值,支援volatile load語義。
   * 
   * @param obj the object containing the field to read.
   *    包含需要去讀取的field的物件
   * @param offset the offset of the long field within <code>obj</code>.
   *       <code>obj</code>中long型field的偏移量
   * @see #getLong(Object,long)
   */
  public native long getLongVolatile(Object obj, long offset);
  /***
   * Retrieves the value of the long field at the specified offset in the
   * supplied object.
   * 獲取obj物件中offset偏移地址對應的long型field的值
   * 
   * @param obj the object containing the field to read.
   *    包含需要去讀取的field的物件
   * @param offset the offset of the long field within <code>obj</code>.
   *       <code>obj</code>中long型field的偏移量
   * @see #getLongVolatile(Object,long)
   */
  public native long getLong(Object obj, long offset);
  /***
   * Sets the value of the object field at the specified offset in the
   * supplied object to the given value, with volatile store semantics.
   * 設定obj物件中offset偏移地址對應的object型field的值為指定值。支援volatile store語義
   * 
   * @param obj the object containing the field to modify.
   *    包含需要修改field的物件
   * @param offset the offset of the object field within <code>obj</code>.
   *     <code>obj</code>中object型field的偏移量
   * @param value the new value of the field.
   *       field將被設定的新值
   * @see #putObject(Object,long,Object)
   */
  public native void putObjectVolatile(Object obj, long offset, Object value);
  /***
   * Sets the value of the object field at the specified offset in the
   * supplied object to the given value.
   * 設定obj物件中offset偏移地址對應的object型field的值為指定值。
   * 
   * @param obj the object containing the field to modify.
   *    包含需要修改field的物件
   * @param offset the offset of the object field within <code>obj</code>.
   *     <code>obj</code>中object型field的偏移量
   * @param value the new value of the field.
   *       field將被設定的新值
   * @see #putObjectVolatile(Object,long,Object)
   */
  public native void putObject(Object obj, long offset, Object value);
  /***
   * Retrieves the value of the object field at the specified offset in the
   * supplied object with volatile load semantics.
   * 獲取obj物件中offset偏移地址對應的object型field的值,支援volatile load語義。
   * 
   * @param obj the object containing the field to read.
   *    包含需要去讀取的field的物件
   * @param offset the offset of the object field within <code>obj</code>.
   *       <code>obj</code>中object型field的偏移量
   */
  public native Object getObjectVolatile(Object obj, long offset);
  /***
   * Returns the offset of the first element for a given array class.
   * To access elements of the array class, this value may be used along with
   * with that returned by 
   * <a href="#arrayIndexScale"><code>arrayIndexScale</code></a>,
   * if non-zero.
   * 獲取給定陣列中第一個元素的偏移地址。
   * 為了存取陣列中的元素，這個偏移地址與<a href="#arrayIndexScale"><code>arrayIndexScale
   * </code></a>方法的非0返回值一起被使用。
   * @param arrayClass the class for which the first element's address should
   *                   be obtained.
   *                   第一個元素地址被獲取的class
   * @return the offset of the first element of the array class.
   *    陣列第一個元素 的偏移地址
   * @see arrayIndexScale(Class)
   */
  public native int arrayBaseOffset(Class arrayClass);
  /***
   * Returns the scale factor used for addressing elements of the supplied
   * array class.  Where a suitable scale factor can not be returned (e.g.
   * for primitive types), zero should be returned.  The returned value
   * can be used with 
   * <a href="#arrayBaseOffset"><code>arrayBaseOffset</code></a>
   * to access elements of the class.
   * 獲取使用者給定陣列定址的換算因子.一個合適的換算因子不能返回的時候(例如：基本型別),
   * 返回0.這個返回值能夠與<a href="#arrayBaseOffset"><code>arrayBaseOffset</code>
   * </a>一起使用去存取這個陣列class中的元素
   * 
   * @param arrayClass the class whose scale factor should be returned.
   * @return the scale factor, or zero if not supported for this array class.
   */
  public native int arrayIndexScale(Class arrayClass);
  
  /***
   * Releases the block on a thread created by 
   * <a href="#park"><code>park</code></a>.  This method can also be used
   * to terminate a blockage caused by a prior call to <code>park</code>.
   * This operation is unsafe, as the thread must be guaranteed to be
   * live.  This is true of Java, but not native code.
   * 釋放被<a href="#park"><code>park</code></a>建立的在一個執行緒上的阻塞.這個
   * 方法也可以被使用來終止一個先前呼叫<code>park</code>導致的阻塞.
   * 這個操作操作時不安全的,因此執行緒必須保證是活的.這是java程式碼不是native程式碼。
   * @param thread the thread to unblock.
   *           要解除阻塞的執行緒
   */
  public native void unpark(Thread thread);
  /***
   * Blocks the thread until a matching 
   * <a href="#unpark"><code>unpark</code></a> occurs, the thread is
   * interrupted or the optional timeout expires.  If an <code>unpark</code>
   * call has already occurred, this also counts.  A timeout value of zero
   * is defined as no timeout.  When <code>isAbsolute</code> is
   * <code>true</code>, the timeout is in milliseconds relative to the
   * epoch.  Otherwise, the value is the number of nanoseconds which must
   * occur before timeout.  This call may also return spuriously (i.e.
   * for no apparent reason).
   * 阻塞一個執行緒直到<a href="#unpark"><code>unpark</code></a>出現、執行緒
   * 被中斷或者timeout時間到期。如果一個<code>unpark</code>呼叫已經出現了，
   * 這裡只計數。timeout為0表示永不過期.當<code>isAbsolute</code>為true時，
   * timeout是相對於新紀元之後的毫秒。否則這個值就是超時前的納秒數。這個方法執行時
   * 也可能不合理地返回(沒有具體原因)
   * 
   * @param isAbsolute true if the timeout is specified in milliseconds from
   *                   the epoch.
   *                   如果為true timeout的值是一個相對於新紀元之後的毫秒數
   * @param time either the number of nanoseconds to wait, or a time in
   *             milliseconds from the epoch to wait for.
   *             可以是一個要等待的納秒數，或者是一個相對於新紀元之後的毫秒數直到
   *             到達這個時間點
   */
  public native void park(boolean isAbsolute, long time);
}