/*
* This file is part of NucleusFramework for Bukkit, licensed under the MIT License (MIT).
*
* Copyright (c) JCThePants (www.jcwhatever.com)
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package com.jcwhatever.nucleus.collections.timed;
import com.google.common.collect.Multimap;
import com.google.common.collect.Multiset;
import com.jcwhatever.nucleus.Nucleus;
import com.jcwhatever.nucleus.collections.wrap.CollectionWrapper;
import com.jcwhatever.nucleus.collections.wrap.MapWrapper;
import com.jcwhatever.nucleus.collections.wrap.SetWrapper;
import com.jcwhatever.nucleus.collections.wrap.SyncStrategy;
import com.jcwhatever.nucleus.managed.scheduler.IScheduledTask;
import com.jcwhatever.nucleus.managed.scheduler.Scheduler;
import com.jcwhatever.nucleus.mixins.IPluginOwned;
import com.jcwhatever.nucleus.utils.CollectionUtils;
import com.jcwhatever.nucleus.utils.PreCon;
import com.jcwhatever.nucleus.utils.Rand;
import com.jcwhatever.nucleus.utils.TimeScale;
import com.jcwhatever.nucleus.utils.observer.update.IUpdateSubscriber;
import com.jcwhatever.nucleus.utils.observer.update.NamedUpdateAgents;
import com.jcwhatever.nucleus.utils.performance.pool.IPoolElementFactory;
import com.jcwhatever.nucleus.utils.performance.pool.SimpleConcurrentPool;
import org.bukkit.plugin.Plugin;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Set;
import java.util.WeakHashMap;
import javax.annotation.Nullable;
/**
* An encapsulated {@link Multimap} where each key has an individual lifespan that
* when ended, causes the item to be removed.
*
* <p>The lifespan can be reset by re-adding a key.</p>
*
* <p>Items can be added using the default lifespan time or a lifespan can be specified per item.</p>
*
* <p>Subscribers that are added to track when an item expires or the collection is
* empty will have a varying degree of resolution up to 10 ticks, meaning the subscriber
* may be notified up to 10 ticks after an element expires (but not before).</p>
*
* <p>Getter operations cease to return an element within approximately 50 milliseconds
* (1 tick) of expiring.</p>
*
* <p>Thread safe.</p>
*
* <p>The maps iterators must be used inside a synchronized block which locks the
* map instance. Otherwise, a {@link java.lang.IllegalStateException} is thrown.</p>
*/
public abstract class TimedMultimap<K, V> implements Multimap<K, V>, IPluginOwned {
// The minimum interval the cleanup is allowed to run at.
// Used to prevent cleanup from being run too often.
private static final int MIN_CLEANUP_INTERVAL_MS = 50;
// The interval the janitor runs at
private static final int JANITOR_INTERVAL_TICKS = 10;
// random initial delay interval for janitor, random to help spread out
// task execution in relation to other scheduled tasks
private static final int JANITOR_INITIAL_DELAY_TICKS = Rand.getInt(1, 9);
private static final Map<TimedMultimap, Void> _instances = new WeakHashMap<>(10);
private static IScheduledTask _janitor;
private final Plugin _plugin;
private final Multimap<K, V> _map;
private final Map<K, ExpireInfo<K>> _expireMap;
private final int _lifespan;
private final TimeScale _timeScale;
private final transient KeySetWrapper _keySet;
private final transient ValuesWrapper _values;
private final transient EntriesWrapper _entries;
private final transient AsMapWrapper _asMap;
private final transient Object _sync;
private final transient SyncStrategy _strategy;
private transient long _nextCleanup;
private final transient NamedUpdateAgents _agents = new NamedUpdateAgents();
private final transient List<Map.Entry<K, ExpireInfo<K>>> _cleanupList = new ArrayList<>(20);
private final transient SimpleConcurrentPool<ExpireInfo> _expirePool;
/**
* Constructor.
*
* <p>Default lifespan is 20 ticks.</p>
*/
public TimedMultimap(Plugin plugin) {
this(plugin, 20, TimeScale.TICKS);
}
/**
* Constructor.
*
* @param defaultLifespan The lifespan used when one is not specified.
* @param timeScale The lifespan timescale.
*/
public TimedMultimap(Plugin plugin, int defaultLifespan, TimeScale timeScale) {
PreCon.notNull(plugin);
PreCon.positiveNumber(defaultLifespan);
PreCon.notNull(timeScale);
_plugin = plugin;
_sync = this;
_strategy = new SyncStrategy(this);
_lifespan = defaultLifespan * timeScale.getTimeFactor();
_timeScale = timeScale;
_map = createMultimap();
_expireMap = new HashMap<>(_map.keySet().size() + 5);
_keySet = new KeySetWrapper();
_values = new ValuesWrapper();
_entries = new EntriesWrapper();
_asMap = new AsMapWrapper();
_expirePool = new SimpleConcurrentPool<ExpireInfo>(50,
new IPoolElementFactory<ExpireInfo>() {
@Override
public ExpireInfo create() {
return new ExpireInfo<>(TimedMultimap.this);
}
});
synchronized (_instances) {
_instances.put(this, null);
}
startJanitor();
}
/**
* Put an item into the map using the specified lifespan in
* the time scale specified in the constructor..
*
* @param key The item key.
* @param value The item to add.
* @param lifespan The items lifespan.
*/
public boolean put(K key, V value, long lifespan) {
return put(key, value, lifespan, _timeScale);
}
/**
* Put an item into the map using the specified lifespan in
* the time scale specified.
*
* @param key The item key.
* @param value The item to add.
* @param lifespan The items lifespan.
* @param timeScale The time scale of the specified lifespan
*/
public boolean put(K key, V value, long lifespan, TimeScale timeScale) {
PreCon.notNull(key);
PreCon.notNull(value);
PreCon.positiveNumber(lifespan);
PreCon.notNull(timeScale);
synchronized (_sync) {
if (_map.put(key, value)) {
@SuppressWarnings("unchecked")
ExpireInfo<K> expireInfo = (ExpireInfo<K>)_expirePool.retrieve();
assert expireInfo != null;
_expireMap.put(key, expireInfo.set(key, lifespan, timeScale));
return true;
}
return false;
}
}
/**
* Put a map of items into the map using the specified lifespan
* in the time scale specified in the constructor..
*
* @param entries The map to add.
* @param lifespan The lifespan of the added items.
*/
public void putAll(Map<? extends K, ? extends V> entries, int lifespan) {
putAll(entries, lifespan, _timeScale);
}
/**
* Put a map of items into the map using the specified lifespan
* int the time scale specified.
*
* @param entries The map to add.
* @param lifespan The lifespan of the added items.
* @param timeScale The time scale of the specified lifespan.
*/
public void putAll(Map<? extends K, ? extends V> entries, int lifespan, TimeScale timeScale) {
PreCon.notNull(entries);
PreCon.positiveNumber(lifespan);
PreCon.notNull(timeScale);
synchronized (_sync) {
for (Map.Entry<? extends K, ? extends V> entry : entries.entrySet()) {
put(entry.getKey(), entry.getValue(), lifespan, timeScale);
}
}
}
/**
* Set the maximum size of the internal object pool used
* for pooling internal instances.
*
* @param poolSize The maximum pool size. -1 for "infinite".
*
* @return Self for chaining.
*/
public TimedMultimap<K, V> setMaxPoolSize(int poolSize) {
_expirePool.setMaxSize(poolSize);
return this;
}
/**
* Get the maximum size of the internal object pool used
* for pooling internal instances.
*/
public int getMaxPoolSize() {
return _expirePool.maxSize();
}
/**
* Register a subscriber to be notified when an entry's lifespan ends.
*
* @param subscriber The subscriber.
*
* @return Self for chaining.
*/
public TimedMultimap<K, V> onLifespanEnd(IUpdateSubscriber<Entry<K, Collection<V>>> subscriber) {
PreCon.notNull(subscriber);
_agents.getAgent("onLifespanEnd").addSubscriber(subscriber);
return this;
}
/**
* Register a subscriber to be notified when the collection becomes
* empty due to an entry's lifespan ending.
*
* @param subscriber The subscriber.
*
* @return Self for chaining.
*/
public TimedMultimap<K, V> onEmpty(IUpdateSubscriber<TimedMultimap<K, V>> subscriber) {
PreCon.notNull(subscriber);
_agents.getAgent("onEmpty").addSubscriber(subscriber);
return this;
}
/**
* Invoked once during the constructor to create the
* encapsulated {@link Multimap}.
*/
protected abstract Multimap<K, V> createMultimap();
@Override
public Plugin getPlugin() {
return _plugin;
}
@Override
public void clear() {
_map.clear();
_expireMap.clear();
}
@Override
public int size() {
synchronized (_sync) {
cleanup();
return _map.size();
}
}
@Override
public boolean isEmpty() {
synchronized (_sync) {
cleanup();
return _map.isEmpty();
}
}
@Override
public boolean containsKey(Object key) {
PreCon.notNull(key);
synchronized (_sync) {
return !isExpiredRemove(key) &&
_map.containsKey(key);
}
}
@Override
public boolean containsValue(@Nullable Object value) {
synchronized (_sync) {
cleanup();
return _map.containsValue(value);
}
}
@Override
public boolean containsEntry(@Nullable Object o, @Nullable Object o1) {
synchronized (_sync) {
cleanup();
return _map.containsEntry(o, o1);
}
}
@Override
@Nullable
public Collection<V> get(K key) {
PreCon.notNull(key);
synchronized (_sync) {
if (isExpiredRemove(key)) {
return CollectionUtils.unmodifiableList();
}
return _map.get(key);
}
}
@Override
public Set<K> keySet() {
return _keySet;
}
@Override
public Multiset<K> keys() {
return _map.keys(); // TODO: Wrap
}
@Override
public Collection<V> values() {
return _values;
}
@Override
public Collection<Entry<K, V>> entries() {
return _entries;
}
@Override
public Map<K, Collection<V>> asMap() {
return _asMap;
}
@Override
@Nullable
public boolean put(K key, V value) {
PreCon.notNull(key);
PreCon.notNull(value);
return put(key, value, _lifespan, TimeScale.TICKS);
}
@Override
public boolean putAll(Multimap<? extends K, ? extends V> entries) {
PreCon.notNull(entries);
boolean isChanged = false;
for (Map.Entry<? extends K, ? extends V> entry : entries.entries()) {
isChanged = put(entry.getKey(), entry.getValue()) || isChanged;
}
return isChanged;
}
@Override
public Collection<V> replaceValues(@Nullable K k, Iterable<? extends V> iterable) {
synchronized (_sync) {
Collection<V> result = _map.replaceValues(k, iterable);
@SuppressWarnings("unchecked")
ExpireInfo<K> expireInfo = (ExpireInfo<K>)_expirePool.retrieve();
assert expireInfo != null;
_expireMap.put(k, expireInfo.set(k, _lifespan, TimeScale.MILLISECONDS));
return result;
}
}
@Override
public Collection<V> removeAll(@Nullable Object o) {
Collection<V> result = _map.removeAll(o);
//noinspection unchecked,SuspiciousMethodCalls
ExpireInfo<K> expireInfo = _expireMap.remove(o);
if (expireInfo != null)
expireInfo.recycle();
return result;
}
@Override
public boolean remove(Object key, Object value) {
PreCon.notNull(key);
synchronized (_sync) {
return _map.remove(key, value);
}
}
@Override
public boolean putAll(@Nullable K k, Iterable<? extends V> iterable) {
if (iterable == null)
return false;
boolean isChanged = false;
for (V element : iterable) {
isChanged = put(k, element) || isChanged;
}
return isChanged;
}
private void onLifespanEnd(final K key, final Collection<V> values) {
_agents.update("onLifespanEnd", getEntry(key, values));
if (isEmpty()) {
_agents.update("onEmpty", this);
}
}
private boolean isExpiredRemove(Object key) {
//noinspection SuspiciousMethodCalls
ExpireInfo<K> info = _expireMap.get(key);
if (info == null)
return true;
if (info.isExpired()) {
//noinspection SuspiciousMethodCalls
Collection<V> collection = _map.removeAll(key);
//noinspection SuspiciousMethodCalls
_expireMap.remove(key);
onLifespanEnd(info.key, collection);
info.recycle();
return true;
}
return false;
}
private void cleanup() {
if (_expireMap.isEmpty())
return;
// prevent cleanup from running too often
if (_nextCleanup > System.currentTimeMillis())
return;
_nextCleanup = System.currentTimeMillis() + MIN_CLEANUP_INTERVAL_MS;
_cleanupList.addAll(_expireMap.entrySet());
// iterate over entry set for items to remove
for (Map.Entry<K, ExpireInfo<K>> entry : _cleanupList) {
// check if entry is expired
if (!entry.getValue().isExpired())
continue;
_expireMap.remove(entry.getKey());
Collection<V> removed = _map.removeAll(entry.getKey());
// notify subscribers
onLifespanEnd(entry.getKey(), removed);
entry.getValue().recycle();
}
_cleanupList.clear();
}
private Entry<K, Collection<V>> getEntry(final K key, final Collection<V> values) {
return new Entry<K, Collection<V>>() {
Collection<V> value = values;
@Override
public K getKey() {
return key;
}
@Override
public Collection<V> getValue() {
return values;
}
@Override
public Collection<V> setValue(Collection<V> value) {
Collection<V> prev = this.value;
this.value = value;
return prev;
}
};
}
private void startJanitor() {
if (_janitor != null)
return;
synchronized (_instances) {
if (_janitor != null)
return;
_janitor = Scheduler.runTaskRepeatAsync(
Nucleus.getPlugin(), JANITOR_INITIAL_DELAY_TICKS, JANITOR_INTERVAL_TICKS, new Runnable() {
List<TimedMultimap> maps = new ArrayList<>(20);
@Override
public void run() {
synchronized (_instances) {
maps.addAll(_instances.keySet());
}
for (TimedMultimap map : maps) {
if (!map._plugin.isEnabled()) {
synchronized (_instances) {
_instances.remove(map);
}
continue;
}
synchronized (map._sync) {
map.cleanup();
}
}
maps.clear();
}
});
}
}
private static final class ExpireInfo<K> {
TimedMultimap<K, ?> parent;
K key;
long expires;
boolean isRecycled;
ExpireInfo(TimedMultimap<K, ?> parent) {
this.parent = parent;
}
ExpireInfo<K> set(K key, long lifespan, TimeScale timeScale) {
this.key = key;
this.expires = System.currentTimeMillis() + (lifespan * timeScale.getTimeFactor());
this.isRecycled = false;
return this;
}
void recycle() {
if (this.isRecycled)
return;
this.isRecycled = true;
this.key = null;
this.parent._expirePool.recycle(this);
}
boolean isExpired() {
return System.currentTimeMillis() >= expires;
}
}
private final class KeySetWrapper extends SetWrapper<K> {
KeySetWrapper() {
super(TimedMultimap.this._strategy);
}
@Override
protected boolean onPreAdd(K k) {
throw new UnsupportedOperationException();
}
@Override
protected void onRemoved(Object o) {
synchronized (TimedMultimap.this._sync) {
//noinspection SuspiciousMethodCalls
ExpireInfo<K> info = _expireMap.remove(o);
if (info != null)
info.recycle();
}
}
@Override
protected void onClear(Collection<K> values) {
synchronized (TimedMultimap.this._sync) {
for (ExpireInfo info : _expireMap.values()) {
info.recycle();
}
_expireMap.clear();
}
}
@Override
protected Set<K> set() {
return _map.keySet();
}
}
private final class ValuesWrapper extends CollectionWrapper<V> {
ValuesWrapper() {
super(TimedMultimap.this._strategy);
}
@Override
protected boolean onPreAdd(V v) {
throw new UnsupportedOperationException();
}
@Override
protected boolean onPreRemove(Object o) {
throw new UnsupportedOperationException();
}
@Override
protected void onClear(Collection<V> values) {
throw new UnsupportedOperationException();
}
@Override
protected final Collection<V> collection() {
return _map.values();
}
}
private final class EntriesWrapper extends CollectionWrapper<Entry<K, V>> {
EntriesWrapper() {
super(TimedMultimap.this._strategy);
}
@Override
protected void onAdded(Entry<K, V> entry) {
synchronized (TimedMultimap.this._sync) {
@SuppressWarnings("unchecked")
ExpireInfo<K> expireInfo = (ExpireInfo<K>)_expirePool.retrieve();
assert expireInfo != null;
_expireMap.put(entry.getKey(),
expireInfo.set(entry.getKey(), _lifespan, TimeScale.MILLISECONDS));
}
}
@Override
protected boolean onPreRemove(Object o) {
throw new UnsupportedOperationException();
}
@Override
protected void onClear(Collection<Entry<K, V>> values) {
synchronized (TimedMultimap.this._sync) {
for (ExpireInfo<K> info : _expireMap.values()) {
info.recycle();
}
_expireMap.clear();
}
}
@Override
protected Collection<Entry<K, V>> collection() {
return _map.entries();
}
}
private final class AsMapWrapper extends MapWrapper<K, Collection<V>> {
AsMapWrapper() {
super(TimedMultimap.this._strategy);
}
@Override
protected Map<K, Collection<V>> map() {
return _map.asMap();
}
}
}