Enhance class & function documentation in LFUcache.java (#5583)

* Enhance class & function documentation in `LFUcache.java`

* Fix

---------

Co-authored-by: Alex Klymenko <alexanderklmn@gmail.com>
This commit is contained in:
Hardik Pawar
2024-10-06 23:11:29 +05:30
committed by GitHub
parent b190cb72de
commit afc06d5632

View File

@ -4,11 +4,27 @@ import java.util.HashMap;
import java.util.Map; import java.util.Map;
/** /**
* Java program for LFU Cache (https://en.wikipedia.org/wiki/Least_frequently_used) * The {@code LFUCache} class implements a Least Frequently Used (LFU) cache.
* An LFU cache evicts the least frequently used item when the cache reaches its capacity.
* It keeps track of how many times each item is used and maintains a doubly linked list
* for efficient addition and removal of items based on their frequency of use.
*
* @param <K> The type of keys maintained by this cache.
* @param <V> The type of mapped values.
*
* <p>
* Reference: <a href="https://en.wikipedia.org/wiki/Least_frequently_used">LFU Cache - Wikipedia</a>
* </p>
*
* @author Akshay Dubey (https://github.com/itsAkshayDubey) * @author Akshay Dubey (https://github.com/itsAkshayDubey)
*/ */
public class LFUCache<K, V> { public class LFUCache<K, V> {
/**
* The {@code Node} class represents an element in the LFU cache.
* Each node contains a key, a value, and a frequency count.
* It also has pointers to the previous and next nodes in the doubly linked list.
*/
private class Node { private class Node {
private final K key; private final K key;
private V value; private V value;
@ -16,6 +32,13 @@ public class LFUCache<K, V> {
private Node previous; private Node previous;
private Node next; private Node next;
/**
* Constructs a new {@code Node} with the specified key, value, and frequency.
*
* @param key The key associated with this node.
* @param value The value stored in this node.
* @param frequency The frequency of usage of this node.
*/
Node(K key, V value, int frequency) { Node(K key, V value, int frequency) {
this.key = key; this.key = key;
this.value = value; this.value = value;
@ -29,10 +52,19 @@ public class LFUCache<K, V> {
private final int capacity; private final int capacity;
private static final int DEFAULT_CAPACITY = 100; private static final int DEFAULT_CAPACITY = 100;
/**
* Constructs an LFU cache with the default capacity.
*/
public LFUCache() { public LFUCache() {
this(DEFAULT_CAPACITY); this(DEFAULT_CAPACITY);
} }
/**
* Constructs an LFU cache with the specified capacity.
*
* @param capacity The maximum number of items that the cache can hold.
* @throws IllegalArgumentException if the specified capacity is less than or equal to zero.
*/
public LFUCache(int capacity) { public LFUCache(int capacity) {
if (capacity <= 0) { if (capacity <= 0) {
throw new IllegalArgumentException("Capacity must be greater than zero."); throw new IllegalArgumentException("Capacity must be greater than zero.");
@ -42,10 +74,12 @@ public class LFUCache<K, V> {
} }
/** /**
* Retrieves the value for the given key from the cache. Increases the frequency of the node. * Retrieves the value associated with the given key from the cache.
* If the key exists, the node's frequency is increased and the node is repositioned
* in the linked list based on its updated frequency.
* *
* @param key The key to look up. * @param key The key whose associated value is to be returned.
* @return The value associated with the key, or null if the key is not present. * @return The value associated with the key, or {@code null} if the key is not present in the cache.
*/ */
public V get(K key) { public V get(K key) {
Node node = cache.get(key); Node node = cache.get(key);
@ -59,10 +93,12 @@ public class LFUCache<K, V> {
} }
/** /**
* Adds or updates a key-value pair in the cache. If the cache is full, the least frequently used item is evicted. * Inserts or updates a key-value pair in the cache.
* If the key already exists, the value is updated and its frequency is incremented.
* If the cache is full, the least frequently used item is removed before inserting the new item.
* *
* @param key The key to insert or update. * @param key The key associated with the value to be inserted or updated.
* @param value The value to insert or update. * @param value The value to be inserted or updated.
*/ */
public void put(K key, V value) { public void put(K key, V value) {
if (cache.containsKey(key)) { if (cache.containsKey(key)) {
@ -73,7 +109,7 @@ public class LFUCache<K, V> {
addNodeWithUpdatedFrequency(node); addNodeWithUpdatedFrequency(node);
} else { } else {
if (cache.size() >= capacity) { if (cache.size() >= capacity) {
cache.remove(this.head.key); cache.remove(this.head.key); // Evict least frequently used item
removeNode(head); removeNode(head);
} }
Node node = new Node(key, value, 1); Node node = new Node(key, value, 1);
@ -84,8 +120,9 @@ public class LFUCache<K, V> {
/** /**
* Adds a node to the linked list in the correct position based on its frequency. * Adds a node to the linked list in the correct position based on its frequency.
* The linked list is ordered by frequency, with the least frequently used node at the head.
* *
* @param node The node to add. * @param node The node to be inserted into the list.
*/ */
private void addNodeWithUpdatedFrequency(Node node) { private void addNodeWithUpdatedFrequency(Node node) {
if (tail != null && head != null) { if (tail != null && head != null) {
@ -122,9 +159,10 @@ public class LFUCache<K, V> {
} }
/** /**
* Removes a node from the linked list. * Removes a node from the doubly linked list.
* This method ensures that the pointers of neighboring nodes are properly updated.
* *
* @param node The node to remove. * @param node The node to be removed from the list.
*/ */
private void removeNode(Node node) { private void removeNode(Node node) {
if (node.previous != null) { if (node.previous != null) {