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
* 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) {