Package studio.mevera.imperat.events

Enum Class ExecutionStrategy

java.lang.Object
java.lang.Enum<ExecutionStrategy>
studio.mevera.imperat.events.ExecutionStrategy
All Implemented Interfaces:
Serializable, Comparable<ExecutionStrategy>, Constable
public enum ExecutionStrategy extends Enum<ExecutionStrategy>
Defines the execution strategy for event handlers registered with the EventBus.

Each handler can be registered with a specific execution strategy, determining whether it runs synchronously or asynchronously when an event is posted.

Synchronous Execution (SYNC)

Handlers execute in the same thread that posted the event. The EventBus.post(Event) method blocks until all synchronous handlers complete.

  • Use when: Handler must complete before the event source continues
  • Use when: Handler modifies event data that other handlers need
  • Use when: Handler performs quick operations (validation, filtering)
  • Use when: Thread-local context must be preserved

Asynchronous Execution (ASYNC)

Handlers are submitted to an ExecutorService and execute in a separate thread. The EventBus.post(Event) method returns immediately without waiting for async handlers to complete.

  • Use when: Handler performs slow I/O operations (database, network)
  • Use when: Handler is non-critical and can run in background
  • Use when: Handler doesn't need to block the event source
  • Use when: Handler logs or records metrics asynchronously

Mixed Execution Order

When both sync and async handlers are registered for the same event type:

  1. All SYNC handlers execute sequentially in priority order
  2. All ASYNC handlers are submitted in priority order
  3. The EventBus.post(Event) method returns after sync handlers complete
  4. Async handlers may still be running after post() returns

Example: Critical Synchronous Handler


 // Validation must complete before event continues
 eventBus.register(PlayerChatEvent.class,
     event -> {
         if (containsProfanity(event.getMessage())) {
             event.setCancelled(true);
             event.getPlayer().sendMessage("Please avoid profanity!");
         }
     },
     Priority.HIGH,
     ExecutionStrategy.SYNC
 );

Example: Background Async Handler


 // Log to database asynchronously without blocking
 eventBus.register(PlayerChatEvent.class,
     event -> {
         if (!event.isCancelled()) {
             database.logChatMessage(
                 event.getPlayer().getId(),
                 event.getMessage(),
                 System.currentTimeMillis()
             );
         }
     },
     Priority.NORMAL,
     ExecutionStrategy.ASYNC
 );

Example: Mixed Strategies


 // High priority sync validation
 eventBus.register(CommandPreRegistrationEvent.class,
     event -> {
         if (!isCommandAllowed(event.getCommand())) {
             event.setCancelled(true);
         }
     },
     Priority.HIGH,
     ExecutionStrategy.SYNC
 );

 // Low priority async logging
 eventBus.register(CommandPreRegistrationEvent.class,
     event -> {
         logger.info("RootCommand registration attempt: {}",
                     event.getCommand().getName());
     },
     Priority.LOW,
     ExecutionStrategy.ASYNC
 );

Example: Event Modification


 // Sync handlers can modify event data for subsequent handlers
 eventBus.register(PlayerChatEvent.class,
     event -> {
         // Transform message before other handlers see it
         String filtered = filterProfanity(event.getMessage());
         event.setMessage(filtered);
     },
     Priority.HIGHEST,
     ExecutionStrategy.SYNC
 );

 eventBus.register(PlayerChatEvent.class,
     event -> {
         // This handler sees the filtered message
         broadcast(event.getMessage());
     },
     Priority.NORMAL,
     ExecutionStrategy.SYNC
 );

Performance Considerations

  • SYNC: Fast execution, blocks caller, preserves order
  • ASYNC: Non-blocking, parallel execution, eventual completion
  • Thread Safety: Async handlers must be thread-safe
  • CommandContext: Async handlers lose thread-local context
Since:
1.0
See Also:

  • Enum Constant Details

    • SYNC

      public static final ExecutionStrategy SYNC
      Handler executes synchronously in the posting thread.

      The EventBus.post(Event) call blocks until this handler completes. Use for critical operations that must finish before the event source continues.

    • ASYNC

      public static final ExecutionStrategy ASYNC
      Handler executes asynchronously in a separate thread.

      The EventBus.post(Event) call returns immediately without waiting. Use for slow operations, logging, or non-critical background tasks.

  • Method Details

    • values

      public static ExecutionStrategy[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static ExecutionStrategy valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null