From 8c4b4fcaa41a7b59e24378bc21fd01d950bcaf22 Mon Sep 17 00:00:00 2001 From: "Kristian S. Stangeland" Date: Wed, 21 Nov 2012 02:42:18 +0100 Subject: [PATCH] Advertise the incrementProcessingDelay() function. Discurage plugins of re-sending cancelled packets, as it makes it impossible for other plugins to take part in the processing. Assume plugin A delays transmission of packet X by cancelling the event, and then retransmitting X outside the filters. It is then impossible for another plugin B to extend the delay without fighting plugin A for control over the packet, for instance by decreasing the listener priority and cancelling first. It is much better for plugin A to call incrementProcessingDelay() in an asynchronous listener. Then plugin B can do the same, and the packet will be sent after both plugins has called signalProcessingDone(). --- .../com/comphenix/protocol/AsynchronousManager.java | 3 +++ .../comphenix/protocol/async/AsyncFilterManager.java | 6 +++++- .../protocol/async/AsyncListenerHandler.java | 3 ++- .../com/comphenix/protocol/async/AsyncMarker.java | 6 ++---- .../com/comphenix/protocol/events/PacketEvent.java | 11 ++++++++++- 5 files changed, 22 insertions(+), 7 deletions(-) diff --git a/ProtocolLib/src/main/java/com/comphenix/protocol/AsynchronousManager.java b/ProtocolLib/src/main/java/com/comphenix/protocol/AsynchronousManager.java index 4d1d8f35..4a7d76d1 100644 --- a/ProtocolLib/src/main/java/com/comphenix/protocol/AsynchronousManager.java +++ b/ProtocolLib/src/main/java/com/comphenix/protocol/AsynchronousManager.java @@ -22,6 +22,7 @@ import java.util.Set; import org.bukkit.plugin.Plugin; import com.comphenix.protocol.async.AsyncListenerHandler; +import com.comphenix.protocol.async.AsyncMarker; import com.comphenix.protocol.error.ErrorReporter; import com.comphenix.protocol.events.PacketEvent; import com.comphenix.protocol.events.PacketListener; @@ -35,6 +36,8 @@ public interface AsynchronousManager { /** * Registers an asynchronous packet handler. *

+ * Use {@link AsyncMarker#incrementProcessingDelay()} to delay a packet until its ready to be transmitted. + *

* To start listening asynchronously, pass the getListenerLoop() runnable to a different thread. * @param listener - the packet listener that will recieve these asynchronous events. * @return An asynchrouns handler. diff --git a/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncFilterManager.java b/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncFilterManager.java index 92de92a1..1b3bd8cc 100644 --- a/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncFilterManager.java +++ b/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncFilterManager.java @@ -43,7 +43,9 @@ import com.google.common.collect.Sets; /** * Represents a filter manager for asynchronous packets. - * + *

+ * By using {@link AsyncMarker#incrementProcessingDelay()}, a packet can be delayed without having to block the + * processing thread. * @author Kristian */ public class AsyncFilterManager implements AsynchronousManager { @@ -128,6 +130,8 @@ public class AsyncFilterManager implements AsynchronousManager { /** * Registers an asynchronous packet handler. *

+ * Use {@link AsyncMarker#incrementProcessingDelay()} to delay a packet until its ready to be transmitted. + *

* To start listening asynchronously, pass the getListenerLoop() runnable to a different thread. *

* Asynchronous events will only be executed if a synchronous listener with the same packets is registered. diff --git a/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncListenerHandler.java b/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncListenerHandler.java index 65e4871a..f37511f8 100644 --- a/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncListenerHandler.java +++ b/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncListenerHandler.java @@ -35,7 +35,8 @@ import com.google.common.base.Joiner; /** * Represents a handler for an asynchronous event. - * + *

+ * Use {@link AsyncMarker#incrementProcessingDelay()} to delay a packet until a certain condition has been met. * @author Kristian */ public class AsyncListenerHandler { diff --git a/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncMarker.java b/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncMarker.java index 6cf5147c..7b6b038b 100644 --- a/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncMarker.java +++ b/ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncMarker.java @@ -206,7 +206,7 @@ public class AsyncMarker implements Serializable, Comparable { } /** - * Increment the number of times this packet must be signalled as done before its transmitted. + * Increment the number of times the current packet must be signalled as done before its transmitted. *

* This is useful if an asynchronous listener is waiting for further information before the * packet can be sent to the user. A packet listener MUST eventually call @@ -215,9 +215,7 @@ public class AsyncMarker implements Serializable, Comparable { *

* It is recommended that processing outside a packet listener is wrapped in a synchronized block * using the {@link #getProcessingLock()} method. - *

- * To decrement the processing delay, call signalPacketUpdate. A thread that calls this method - * multiple times must call signalPacketUpdate at least that many times. + * * @return The new processing delay. */ public int incrementProcessingDelay() { diff --git a/ProtocolLib/src/main/java/com/comphenix/protocol/events/PacketEvent.java b/ProtocolLib/src/main/java/com/comphenix/protocol/events/PacketEvent.java index 61062772..c35330cb 100644 --- a/ProtocolLib/src/main/java/com/comphenix/protocol/events/PacketEvent.java +++ b/ProtocolLib/src/main/java/com/comphenix/protocol/events/PacketEvent.java @@ -134,7 +134,16 @@ public class PacketEvent extends EventObject implements Cancellable { } /** - * Sets whether or not the packet should be cancelled. + * Sets whether or not the packet should be cancelled. Uncancelling is possible. + *

+ * Warning: A cancelled packet should never be re-transmitted. Use the asynchronous + * packet manager if you need to perform extensive processing. It should also be used + * if you need to synchronize with the main thread. + *

+ * This ensures that other plugins can work with the same packet. + *

+ * An asynchronous listener can also delay a packet indefinitely without having to block its thread. + * * @param cancel - TRUE if it should be cancelled, FALSE otherwise. */ public void setCancelled(boolean cancel) {