Class LockFreeStack<E>

java.lang.Object
cloud.opencode.base.collections.concurrent.LockFreeStack<E>
Type Parameters:
E - element type | 元素类型
public final class LockFreeStack<E> extends Object
LockFreeStack - Lock-free Concurrent Stack using Treiber's Algorithm LockFreeStack - 使用 Treiber 算法的无锁并发栈

A lock-free stack implementation using CAS (Compare-And-Swap) operations, based on Treiber's algorithm for concurrent stack management.

基于 CAS（比较并交换）操作的无锁栈实现， 采用 Treiber 算法进行并发栈管理。

Features | 主要功能:

  • Lock-free operations - 无锁操作
  • Thread-safe - 线程安全
  • Non-blocking - 非阻塞
  • LIFO ordering - 后进先出顺序

Usage Examples | 使用示例:

LockFreeStack<String> stack = new LockFreeStack<>();

// Push (入栈)
stack.push("item1");
stack.push("item2");

// Pop (出栈) - LIFO order
String item = stack.pop();  // "item2"

// Peek (查看栈顶) - does not remove
String top = stack.peek();  // "item1"

// Can be used from multiple threads - 可从多线程使用

Performance | 性能特性:

  • push: O(1) amortized - push: 均摊 O(1)
  • pop: O(1) amortized - pop: 均摊 O(1)
  • peek: O(1) - peek: O(1)

Security | 安全性:

  • Thread-safe: Yes (lock-free, CAS-based) - 线程安全: 是（无锁，基于 CAS）
  • Null-safe: No (nulls not allowed) - 空值安全: 否（不允许空值）
Since:
JDK 25, opencode-base-collections V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    LockFreeStack()
    Create an empty LockFreeStack.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Remove all elements from the stack.
    boolean
    isEmpty()
    Check if the stack is empty.
    E
    peek()
    Peek at the top element without removing it.
    E
    pop()
    Pop the top element from the stack.
    void
    push(E element)
    Push an element onto the top of the stack.
    int
    size()
    Get the approximate size of the stack.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • LockFreeStack

      public LockFreeStack()
      Create an empty LockFreeStack. 创建空 LockFreeStack。

  • Method Details

    • push

      public void push(E element)
      Push an element onto the top of the stack. 将元素压入栈顶。
      Parameters:
      element - the element to push | 要压入的元素
      Throws:
      NullPointerException - if element is null | 如果元素为 null

    • pop

      public E pop()
      Pop the top element from the stack. 弹出栈顶元素。
      Returns:
      the top element, or null if the stack is empty | 栈顶元素，如果栈为空则返回 null

    • peek

      public E peek()
      Peek at the top element without removing it. 查看栈顶元素但不移除。
      Returns:
      the top element, or null if the stack is empty | 栈顶元素，如果栈为空则返回 null

    • isEmpty

      public boolean isEmpty()
      Check if the stack is empty. 检查栈是否为空。
      Returns:
      true if the stack is empty | 如果栈为空返回 true

    • size

      public int size()
      Get the approximate size of the stack. 获取栈的近似大小。

      Note: In a concurrent environment, this value is approximate and may be briefly inaccurate because top and size are not updated atomically. The returned value is always non-negative.

      注意：在并发环境中，该值为近似值，可能短暂不精确， 因为 top 和 size 不是原子更新的。返回值始终非负。

      Returns:
      approximate number of elements (always ≥ 0) | 近似元素数量（始终 ≥ 0）

    • clear

      public void clear()
      Remove all elements from the stack. 移除栈中所有元素。

      This operation is thread-safe. It atomically swaps the top to null using CAS, then resets the size counter.

      此操作是线程安全的。使用 CAS 原子地将栈顶交换为 null，然后重置大小计数器。