com.comphenix.protocol.async

Class AsyncListenerHandler

java.lang.Object

com.comphenix.protocol.async.AsyncListenerHandler

public class AsyncListenerHandler
extends java.lang.Object

Represents a handler for an asynchronous event.

Use AsyncMarker.incrementProcessingDelay() to delay a packet until a certain condition has been met.

Author:

Kristian

Method Summary

Methods

Modifier and Type	Method and Description
void	cancel() Cancel the handler.
void	enqueuePacket(PacketEvent packet) Queue a packet for processing.
PacketListener	getAsyncListener() Retrieve the current asynchronous packet listener.
java.lang.String	getFriendlyWorkerName(int id) Create a friendly thread name using the following convention:
AsyncRunnable	getListenerLoop() Create a worker that will initiate the listener loop.
org.bukkit.plugin.Plugin	getPlugin() Retrieve the plugin associated with this async listener.
int	getWorkers() Retrieve the current number of registered workers.
boolean	isCancelled() Determine whether or not this asynchronous handler has been cancelled.
void	setWorkers(int count) Set the current number of workers.
void	start() Start a singler worker thread handling the asynchronous listener.
void	start(com.google.common.base.Function<AsyncRunnable,java.lang.Void> executor) Start a singler worker thread handling the asynchronous listener.
void	start(int count) Start multiple worker threads for this listener.
void	stop() Stop a worker thread.
void	stop(int count) Stop the given amount of worker threads.
boolean	syncStart() Start processing packets on the main thread.
boolean	syncStart(long time, java.util.concurrent.TimeUnit unit) Start processing packets on the main thread.
boolean	syncStop() Stop processing packets on the main thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isCancelled

public boolean isCancelled()

Determine whether or not this asynchronous handler has been cancelled.

Returns:

TRUE if it has been cancelled/stopped, FALSE otherwise.

getAsyncListener

public PacketListener getAsyncListener()

Retrieve the current asynchronous packet listener.

Returns:

Current packet listener.

getPlugin

public org.bukkit.plugin.Plugin getPlugin()

Retrieve the plugin associated with this async listener.

Returns:

The plugin.

cancel

public void cancel()

Cancel the handler.

enqueuePacket

public void enqueuePacket(PacketEvent packet)

Queue a packet for processing.

Parameters:

packet - - a packet for processing.

Throws:

java.lang.IllegalStateException - If the underlying packet queue is full.

getListenerLoop

public AsyncRunnable getListenerLoop()

Create a worker that will initiate the listener loop. Note that using stop() to close a specific worker is less efficient than stopping an arbitrary worker.

Warning: Never call the run() method in the main thread.

start

public void start()

Start a singler worker thread handling the asynchronous listener.

start

public void start(com.google.common.base.Function<AsyncRunnable,java.lang.Void> executor)

Start a singler worker thread handling the asynchronous listener.

This method is intended to allow callers to customize the thread priority before the worker loop is actually called. This is simpler than to schedule the worker threads manually.

 listenerHandler.start(new Function<AsyncRunnable, Void>() {
     @Override
     public Void apply(@Nullable AsyncRunnable workerLoop) {
         Thread thread = Thread.currentThread();
         int prevPriority = thread.getPriority();
               
         thread.setPriority(Thread.MIN_PRIORITY);
         workerLoop.run();
         thread.setPriority(prevPriority);
         return null;
     }
   });
 }
 

Parameters:

executor - - a method that will execute the given listener loop.

getFriendlyWorkerName

public java.lang.String getFriendlyWorkerName(int id)

Create a friendly thread name using the following convention:

Protocol Worker {id} - {plugin} - [recv: {packets}, send: {packets}]

Parameters:

id - - the worker ID.

Returns:

A friendly thread name.

syncStart

public boolean syncStart()

Start processing packets on the main thread.

This is useful if you need to synchronize with the main thread in your packet listener, but you're not performing any expensive processing.

Note: Use a asynchronous worker if the packet listener may use more than 0.5 ms of processing time on a single packet. Do as much as possible on the worker thread, and schedule synchronous tasks to use the Bukkit API instead.

Returns:

TRUE if the synchronized processing was successfully started, FALSE if it's already running.

Throws:

java.lang.IllegalStateException - If we couldn't start the underlying task.

syncStart

public boolean syncStart(long time,
                java.util.concurrent.TimeUnit unit)

Start processing packets on the main thread.

This is useful if you need to synchronize with the main thread in your packet listener, but you're not performing any expensive processing.

The processing time parameter gives the upper bound for the amount of time spent processing pending packets. It should be set to a fairly low number, such as 0.5 ms or 1% of a game tick - to reduce the impact on the main thread. Never go beyond 50 milliseconds.

Note: Use a asynchronous worker if the packet listener may exceed the ideal processing time on a single packet. Do as much as possible on the worker thread, and schedule synchronous tasks to use the Bukkit API instead.

Parameters:

time - - the amount of processing time alloted per game tick (20 ticks per second).

unit - - the unit of the processingTime argument.

Returns:

TRUE if the synchronized processing was successfully started, FALSE if it's already running.

Throws:

java.lang.IllegalStateException - If we couldn't start the underlying task.

syncStop

public boolean syncStop()

Stop processing packets on the main thread.

Returns:

TRUE if we stopped any processing tasks, FALSE if it has already been stopped.

start

public void start(int count)

Start multiple worker threads for this listener.

Parameters:

count - - number of worker threads to start.

stop

public void stop()

Stop a worker thread.

stop

public void stop(int count)

Stop the given amount of worker threads.

Parameters:

count - - number of threads to stop.

setWorkers

public void setWorkers(int count)

Set the current number of workers.

This method can only be called with a count of zero when the listener is closing.

Parameters:

count - - new number of workers.

getWorkers

public int getWorkers()

Retrieve the current number of registered workers.

Note that the returned value may be out of data.

Returns:

Number of registered workers.