mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2025-10-28 04:17:38 +00:00
Code Issues Releases Wiki Activity

Add a helper class for working with attached computers

Browse Source 
One of the easiest things to mess up with writing a custom peripheral is
handling attached peripherals. IPeripheral.{attach,detach} are called
from multiple threads, so naive implementations that just store
computers in a set/list will at some point throw a CME.

Historically I've suggested using a concurrent collection (i.e.
ConcurrentHashMap). While this solves the problems of CMEs, it still has
some flaws. If a computer is detached while iterating over the
collection, the iterator will still yield the now-detached peripheral,
causing usages of that computer (e.g. queueEvent) to throw an exception.

The only fix here is to use a lock when updating and iterating over the
collection. This does come with some risks, but I think they are not too
serious:

 - Lock contention: Contention is relatively rare in general (as
   peripheral attach/detach is not especially frequent). If we do see
   contention, both iteration and update actions are cheap, so I would
   not expect the other thread to be blocked for a significant time.

 - Deadlocks: One could imagine an implementation if IComputerAccess
   that holds a lock both when detaching a peripheral and inside
   queueEvent.

   If we queue an event on one thread, and try to detach on the other,
   we could see a deadlock:

     Thread 1                         | Thread 2
    ----------------------------------------------------------
     AttachedComputerSet.queueEvent   | MyModem.detach
      (take lock #1)                  |  (take lock #2)

     -> MyModem.queueEvent            | AttachedComputerSet.remove
      (wait on lock #2)               |  (wait on lock #1)

   Such code would have been broken already (some peripherals already
   use locks), so I'm fairly sure we've fixed this in CC. But definitely
   something to watch out for.

Anyway, the long and short of it:
 - Add a new AttachedComputerSet that can be used to track the computers
   attached to a peripheral. We also mention this in the attach/detach
   docs, to hopefully make it a little more obvoius.

 - Update speakers and monitors to use this new class.
This commit is contained in:
Jonathan Coates
2024-09-22 13:51:11 +01:00
parent 3042950507
commit e9aceca1de
4 changed files with 147 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
projects/core-api/src/main/java/dan200/computercraft/api/peripheral/AttachedComputerSet.java Normal file
View File

@@ -0,0 +1,129 @@
// SPDX-FileCopyrightText: 2024 The CC: Tweaked Developers
//
// SPDX-License-Identifier: MPL-2.0
package dan200.computercraft.api.peripheral;
import javax.annotation.Nullable;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArraySet;
import java.util.concurrent.locks.ReentrantReadWriteLock;
import java.util.function.Consumer;
/**
* A thread-safe collection of computers.
* <p>
* This collection is intended to be used by peripherals that need to maintain a set of all attached computers.
* <p>
* It is recommended to use over Java's built-in concurrent collections (e.g. {@link CopyOnWriteArraySet} or
* {@link ConcurrentHashMap}), as {@link AttachedComputerSet} ensures that computers cannot be accessed after they are
* detached, guaranteeing that {@link NotAttachedException}s will not be thrown.
* <p>
* To ensure this, {@link AttachedComputerSet} is not directly iterable, as we cannot ensure that computers are not
* detached while the iterator is running (and so trying to use the computer would error). Instead, computers should be
* looped over using {@link #forEach(Consumer)}.
*
* <h2>Example</h2>
*
* <pre>{@code
* public class MyPeripheral implements IPeripheral {
* private final AttachedComputerSet computers = new ComputerCollection();
*
* @Override
* public void attach(IComputerAccess computer) {
* computers.add(computer);
* }
*
* @Override
* public void detach(IComputerAccess computer) {
* computers.remove(computer);
* }
* }
* }</pre>
*
* @see IComputerAccess
* @see IPeripheral#attach(IComputerAccess)
* @see IPeripheral#detach(IComputerAccess)
*/
public final class AttachedComputerSet {
private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
private final Set<IComputerAccess> computers = new HashSet<>(0);
/**
* Add a computer to this collection of computers. This should be called from
* {@link IPeripheral#attach(IComputerAccess)}.
*
* @param computer The computer to add.
*/
public void add(IComputerAccess computer) {
lock.writeLock().lock();
try {
computers.add(computer);
} finally {
lock.writeLock().unlock();
}
}
/**
* Remove a computer from this collection of computers. This should be called from
* {@link IPeripheral#detach(IComputerAccess)}.
*
* @param computer The computer to remove.
*/
public void remove(IComputerAccess computer) {
lock.writeLock().lock();
try {
computers.remove(computer);
} finally {
lock.writeLock().unlock();
}
}
/**
* Apply an action to each computer in this collection.
*
* @param action The action to apply.
*/
public void forEach(Consumer<? super IComputerAccess> action) {
lock.readLock().lock();
try {
computers.forEach(action);
} finally {
lock.readLock().unlock();
}
}
/**
* {@linkplain IComputerAccess#queueEvent(String, Object...) Queue an event} on all computers.
*
* @param event The name of the event to queue.
* @param arguments The arguments for this event.
* @see IComputerAccess#queueEvent(String, Object...)
*/
public void queueEvent(String event, @Nullable Object... arguments) {
forEach(c -> c.queueEvent(event, arguments));
}
/**
* Determine if this collection contains any computers.
* <p>
* This method is primarily intended for presentation purposes (such as rendering an icon in the UI if a computer
* is attached to your peripheral). Due to the multi-threaded nature of peripherals, it is not recommended to guard
* any logic behind this check.
* <p>
* For instance, {@code if(computers.hasComputers()) computers.queueEvent("foo");} contains a race condition, as
* there's no guarantee that any computers are still attached within the body of the if statement.
*
* @return Whether this collection is non-empty.
*/
public boolean hasComputers() {
lock.readLock().lock();
try {
return !computers.isEmpty();
} finally {
lock.readLock().unlock();
}
}
}

10
projects/core-api/src/main/java/dan200/computercraft/api/peripheral/IPeripheral.java
View File

@@ -48,8 +48,9 @@ public interface IPeripheral {
* {@code peripheral.call()}. This method can be used to keep track of which computers are attached to the
* peripheral, or to take action when attachment occurs.
* <p>
* Be aware that will be called from both the server thread and ComputerCraft Lua thread, and so must be thread-safe
* and reentrant.
* Be aware that may be called from both the server thread and ComputerCraft Lua thread, and so must be thread-safe
* and reentrant. If you need to store a list of attached computers, it is recommended you use a
* {@link AttachedComputerSet}.
*
* @param computer The interface to the computer that is being attached. Remember that multiple computers can be
* attached to a peripheral at once.
@@ -68,8 +69,9 @@ public interface IPeripheral {
* This method can be used to keep track of which computers are attached to the peripheral, or to take action when
* detachment occurs.
* <p>
* Be aware that this will be called from both the server and ComputerCraft Lua thread, and must be thread-safe
* and reentrant.
* Be aware that this may be called from both the server and ComputerCraft Lua thread, and must be thread-safe
* and reentrant. If you need to store a list of attached computers, it is recommended you use a
* {@link AttachedComputerSet}.
*
* @param computer The interface to the computer that is being detached. Remember that multiple computers can be
* attached to a peripheral at once.