/*
 * Logback: the reliable, generic, fast and flexible logging framework.
 * Copyright (C) 1999-2026, QOS.ch. All rights reserved.
 *
 * This program and the accompanying materials are dual-licensed under
 * either the terms of the Eclipse Public License v2.0 as published by
 * the Eclipse Foundation
 *
 *   or (per the licensee's choosing)
 *
 * under the terms of the GNU Lesser General Public License version 2.1
 * as published by the Free Software Foundation.
 */

package ch.qos.logback.core.util;

import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.ListIterator;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.atomic.AtomicBoolean;

/**
 * A GC-free lock-free thread-safe implementation of the {@link List} interface
 * for use cases where iterations over the list vastly out-number modifications
 * on the list.
 * 
 * <p>
 * Underneath, it wraps an instance of {@link CopyOnWriteArrayList} and exposes
 * a copy of the array used by that instance.
 * 
 * <p>
 * Typical use:
 * </p>
 * 
 * <pre>
 *   COWArrayList&lt;Integer&gt; list = new COWArrayList(new Integer[0]);
 *   
 *   // modify the list
 *   list.add(1);
 *   list.add(2);
 *   
 *   Integer[] intArray = list.asTypedArray();
 *   int sum = 0;
 *   // iteration over the array is thread-safe
 *   for(int i = 0; i &lt; intArray.length; i++) {
 *     sum != intArray[i];
 *   }
 * </pre>
 * 
 * <p>
 * If the list is not modified, then repetitive calls to
 * {@link #asTypedArray()}, {@link #toArray()} and {@link #toArray(Object[])}
 * are guaranteed to be GC-free. Note that iterating over the list using
 * {@link COWArrayList#iterator()} and {@link COWArrayList#listIterator()} are
 * <b>not</b> GC-free.
 * </p>
 * 
 * @author Ceki Gulcu
 * @since 1.1.10
 */
public class COWArrayList<E> implements List<E> {

    // Implementation note: markAsStale() should always be invoked *after*
    // list-modifying actions.
    // If not, readers might get a stale array until the next write. The potential
    // problem is nicely
    // explained by Rob Eden. See
    // https://github.com/qos-ch/logback/commit/32a2047a1adfc#commitcomment-20791176

    AtomicBoolean fresh = new AtomicBoolean(false);
    CopyOnWriteArrayList<E> underlyingList = new CopyOnWriteArrayList<E>();
    E[] ourCopy;
    final E[] modelArray;

    public COWArrayList(E[] modelArray) {
        this.modelArray = modelArray;
    }

    @Override
    public int size() {
        return underlyingList.size();
    }

    @Override
    public boolean isEmpty() {
        return underlyingList.isEmpty();
    }

    @Override
    public boolean contains(Object o) {
        return underlyingList.contains(o);
    }

    @Override
    public Iterator<E> iterator() {
        return underlyingList.iterator();
    }

    private void refreshCopyIfNecessary() {
        if (!isFresh()) {
            refreshCopy();
        }
    }

    private boolean isFresh() {
        return fresh.get();
    }

    private void refreshCopy() {
        ourCopy = underlyingList.toArray(modelArray);
        fresh.set(true);
    }

    @Override
    public Object[] toArray() {
        refreshCopyIfNecessary();
        return ourCopy;
    }

    @SuppressWarnings("unchecked")
    @Override
    public <T> T[] toArray(T[] a) {
        refreshCopyIfNecessary();
        return (T[]) ourCopy;
    }

    /**
     * Return an array of type E[]. The returned array is intended to be iterated
     * over. If the list is modified, subsequent calls to this method will return
     * different/modified array instances.
     * 
     * @return
     */
    public E[] asTypedArray() {
        refreshCopyIfNecessary();
        return ourCopy;
    }

    private void markAsStale() {
        fresh.set(false);
    }

    public void addIfAbsent(E e) {
        underlyingList.addIfAbsent(e);
        markAsStale();
    }

    @Override
    public boolean add(E e) {
        boolean result = underlyingList.add(e);
        markAsStale();
        return result;
    }

    @Override
    public boolean remove(Object o) {
        boolean result = underlyingList.remove(o);
        markAsStale();
        return result;
    }

    @Override
    public boolean containsAll(Collection<?> c) {
        return underlyingList.containsAll(c);
    }

    @Override
    public boolean addAll(Collection<? extends E> c) {
        markAsStale();
        boolean result = underlyingList.addAll(c);
        return result;
    }

    @Override
    public boolean addAll(int index, Collection<? extends E> col) {
        markAsStale();
        boolean result = underlyingList.addAll(index, col);
        return result;
    }

    @Override
    public boolean removeAll(Collection<?> col) {
        markAsStale();
        boolean result = underlyingList.removeAll(col);
        return result;
    }

    @Override
    public boolean retainAll(Collection<?> col) {
        markAsStale();
        boolean result = underlyingList.retainAll(col);
        return result;
    }

    @Override
    public void clear() {
        markAsStale();
        underlyingList.clear();
    }

    @Override
    public E get(int index) {
        refreshCopyIfNecessary();
        return (E) ourCopy[index];
    }

    @Override
    public E set(int index, E element) {
        markAsStale();
        E e = underlyingList.set(index, element);
        return e;
    }

    @Override
    public void add(int index, E element) {
        markAsStale();
        underlyingList.add(index, element);
    }

    @Override
    public E remove(int index) {
        markAsStale();
        E e = (E) underlyingList.remove(index);
        return e;
    }

    @Override
    public int indexOf(Object o) {
        return underlyingList.indexOf(o);
    }

    @Override
    public int lastIndexOf(Object o) {
        return underlyingList.lastIndexOf(o);
    }

    @Override
    public ListIterator<E> listIterator() {
        return underlyingList.listIterator();
    }

    @Override
    public ListIterator<E> listIterator(int index) {
        return underlyingList.listIterator(index);
    }

    @Override
    public List<E> subList(int fromIndex, int toIndex) {
        return underlyingList.subList(fromIndex, toIndex);
    }

}