com.github.benmanes.caffeine.cache.Node Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of caffeine Show documentation
A high performance caching library
There is a newer version: 3.1.8
/*
 * Copyright 2015 Ben Manes. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.github.benmanes.caffeine.cache;

import java.lang.ref.ReferenceQueue;

import javax.annotation.Nonnegative;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.annotation.concurrent.GuardedBy;

import com.github.benmanes.caffeine.cache.AccessOrderDeque.AccessOrder;
import com.github.benmanes.caffeine.cache.WriteOrderDeque.WriteOrder;

/**
 * An entry in the cache containing the key, value, weight, access, and write metadata. The key
 * or value may be held weakly or softly requiring identity comparison.
 *
 * @author [email protected] (Ben Manes)
 */
@SuppressWarnings({"GuardedByChecker", "GuardedByValidator"})
interface Node extends AccessOrder>, WriteOrder> {

  /** Return the key or {@code null} if it has been reclaimed by the garbage collector. */
  @Nullable
  K getKey();

  /**
   * Returns the reference that the cache is holding the entry by. This is either the key if
   * strongly held or a {@link java.lang.ref.WeakReference} to that key.
   */
  @Nonnull
  Object getKeyReference();

  /** Return the value or {@code null} if it has been reclaimed by the garbage collector. */
  @Nullable
  V getValue();

  /**
   * Returns the reference to the value. This is either the value if strongly held or a
   * {@link java.lang.ref.Reference} to that value.
   */
  @Nonnull
  Object getValueReference();

  /**
   * Sets the value, which may be held strongly, weakly, or softly. This update may be set lazily
   * and rely on the memory fence when the lock is released.
   */
  @GuardedBy("this")
  void setValue(@Nonnull V value, @Nullable ReferenceQueue referenceQueue);

  /**
   * Returns {@code true} if the given objects are considered equivalent. A strongly held value is
   * compared by equality and a weakly or softly held value is compared by identity.
   */
  boolean containsValue(@Nonnull Object value);

  /** Returns the weight of this entry from the entry's perspective. */
  @Nonnegative
  @GuardedBy("this")
  default int getWeight() {
    return 1;
  }

  /** Sets the weight from the entry's perspective. */
  @Nonnegative
  @GuardedBy("this")
  default void setWeight(int weight) {}

  /** Returns the weight of this entry from the policy's perspective. */
  @Nonnegative
  @GuardedBy("evictionLock")
  default int getPolicyWeight() {
    return 1;
  }

  /** Sets the weight from the policy's perspective. */
  @Nonnegative
  @GuardedBy("evictionLock")
  default void setPolicyWeight(int weight) {}

  /* ---------------- Health -------------- */

  /** If the entry is available in the hash-table and page replacement policy. */
  @GuardedBy("this")
  boolean isAlive();

  /**
   * If the entry was removed from the hash-table and is awaiting removal from the page
   * replacement policy.
   */
  @GuardedBy("this")
  boolean isRetired();

  /** If the entry was removed from the hash-table and the page replacement policy. */
  @GuardedBy("this")
  boolean isDead();

  /** Sets the node to the retired state. */
  @GuardedBy("this")
  void retire();

  /** Sets the node to the dead state. */
  @GuardedBy("this")
  void die();

  /* ---------------- Access order -------------- */

  int EDEN = 0;
  int PROBATION = 1;
  int PROTECTED = 2;

  /** Returns if the entry is in the Eden or Main space. */
  default boolean inEden() {
    return getQueueType() == EDEN;
  }

  /** Returns if the entry is in the Main space's probation queue. */
  default boolean inMainProbation() {
    return getQueueType() == PROBATION;
  }

  /** Returns if the entry is in the Main space's protected queue. */
  default boolean inMainProtected() {
    return getQueueType() == PROTECTED;
  }

  /** Sets the status to the Main space's probation queue. */
  default void makeMainProbation() {
    setQueueType(PROBATION);
  }

  /** Sets the status to the Main space's protected queue. */
  default void makeMainProtected() {
    setQueueType(PROTECTED);
  }

  /** Returns the queue that the entry's resides in (eden, probation, or protected). */
  default int getQueueType() {
    return EDEN;
  }

  /** Set queue that the entry resides in (eden, probation, or protected). */
  default void setQueueType(int queueType) {
    throw new UnsupportedOperationException();
  }

  /** Returns the time that this entry was last accessed, in ns. */
  default long getAccessTime() {
    return 0L;
  }

  /**
   * Sets the access time in nanoseconds. This update may be set lazily and rely on the memory fence
   * when the lock is released.
   */
  default void setAccessTime(long time) {}

  @Override
  @GuardedBy("evictionLock")
  default Node getPreviousInAccessOrder() {
    return null;
  }

  @Override
  @GuardedBy("evictionLock")
  default void setPreviousInAccessOrder(@Nullable Node prev) {
    throw new UnsupportedOperationException();
  }

  @Override
  @GuardedBy("evictionLock")
  default Node getNextInAccessOrder() {
    return null;
  }

  @Override
  @GuardedBy("evictionLock")
  default void setNextInAccessOrder(@Nullable Node next) {
    throw new UnsupportedOperationException();
  }

  /* ---------------- Write order -------------- */

  /** Returns the time that this entry was last written, in ns. */
  default long getWriteTime() {
    return 0L;
  }

  /**
   * Sets the write time in nanoseconds. This update may be set lazily and rely on the memory fence
   * when the lock is released.
   */
  default void setWriteTime(long time) {}

  /**
   * Atomically sets the write time to the given updated value if the current value equals the
   * expected value and returns if the update was successful.
   */
  default boolean casWriteTime(long expect, long update) {
    throw new UnsupportedOperationException();
  }

  @Override
  @GuardedBy("evictionLock")
  default Node getPreviousInWriteOrder() {
    return null;
  }

  @Override
  @GuardedBy("evictionLock")
  default void setPreviousInWriteOrder(@Nullable Node prev) {
    throw new UnsupportedOperationException();
  }

  @Override
  @GuardedBy("evictionLock")
  default Node getNextInWriteOrder() {
    return null;
  }

  @Override
  @GuardedBy("evictionLock")
  default void setNextInWriteOrder(@Nullable Node next) {
    throw new UnsupportedOperationException();
  }
}