场景介绍

EventHandler开发场景

EventHandler 的主要功能是将 InnerEvent 事件或者 Runnable 任务投递到其他的线程进行处理，其使用的场景包括：

• 开发者需要将 InnerEvent 事件投递到新的线程，按照优先级和延时进行处理。投递时，EventHandler 的优先级可在 IMMEDIATE、HIGH、LOW、IDLE 中选择，并设置合适的 delayTime。
• 开发者需要将 Runnable 任务投递到新的线程，并按照优先级和延时进行处理。投递时， EventHandler 的优先级可在 IMMEDIATE、HIGH、LOW、IDLE 中选择，并设置合适的 delayTime。
• 开发者需要在新创建的线程里投递事件到原线程进行处理。

EventRunner工作模式

EventRunner 的工作模式可以分为托管模式和手动模式。两种模式是在调用 EventRunner 的 create() 方法时，通过选择不同的参数来实现的，详见 API 参考。默认为托管模式。

• 托管模式：不需要开发者调用 run() 和 stop() 方法去启动和停止 EventRunner。当 EventRunner 实例化时，系统调用 run() 来启动 EventRunner；当 EventRunner 不被引用时，系统调用 stop() 来停止 EventRunner。
• 手动模式：需要开发者自行调用 EventRunner 的 run() 方法和 stop() 方法来确保线程的启动和停止。

接口说明

EventHandler

• EventHandler 的属性 Priority (优先级)介绍：

EventRunner 将根据优先级的高低从事件队列中获取事件或者 Runnable 任务进行处理。

• EventHandler 的主要接口介绍：

EventRunner

• EventRunner的主要接口介绍：

InnerEvent

• InnerEvent的属性介绍：

• InnerEvent的主要接口介绍：

开发步骤

EventHandler 投递 InnerEvent 事件

EventHandler 投递 InnerEvent 事件，并按照优先级和延时进行处理，开发步骤如下：

1. 创建 EventHandler 的子类，在子类中重写实现方法 processEvent() 来处理事件。

   private class MyEventHandler extends EventHandler {
       private MyEventHandler(EventRunner runner) {
       super(runner);
       }
       // 重写实现processEvent方法
       @Override
       public void processEvent(InnerEvent event) {
       super.processEvent(event);
       if (event == null) {
               return;
       }
       int eventId = event.eventId;
       long param = event.param;
       switch (eventId | param) {
               case CASE1:
                   // 待执行的操作，由开发者定义
               break;
           default:
           break;
       }
       }
   }

1. 创建 EventRunner，以手动模式为例。

   EventRunner runner = EventRunner.create(false);// create()的参数是 true时，则为托管模式
   // 需要对 EventRunner 的实例进行校验，因为创建 EventRunner 可能失败，如创建线程失败时，创建 EventRunner 失败。
   if (runner == null) {
       return;
   }

1. 创建 EventHandler 子类的实例。

   MyEventHandler myHandler = new MyEventHandler(runner);

1. 获取 InnerEvent 事件。

   // 获取事件实例，其属性 eventId, param, object 由开发者确定，代码中只是示例。
   int eventId1 = 0;
   int eventId2 = 1; 
   long param = 0; 
   Object object = null; 
   InnerEvent event1 = InnerEvent.get(eventId1, param, object);
   InnerEvent event2 = InnerEvent.get(eventId2, param, object);

1. 投递事件，投递的优先级以 IMMEDIATE 为例，延时选择 0ms和 2ms。

   // 优先级 immediate，投递之后立即处理，延时为 0ms，该语句等价于同步投递sendSyncEvent(event1，EventHandler.Priority.immediate);
   myHandler.sendEvent(event1, 0, EventHandler.Priority.IMMEDIATE);
   myHandler.sendEvent(event2, 2, EventHandler.Priority.IMMEDIATE); // 延时 2ms 后立即处理

1. 启动和停止 EventRunner，如果为托管模式，则不需要此步骤。

   runner.run();
   //待执行操作
   runner.stop();// 开发者根据业务需要在适当时机停止 EventRunner

EventHandler 投递 Runnable 任务

EventHandler 投递Runnable 任务，并按照优先级和延时进行处理，开发步骤如下：

1. 创建 EventHandler 的子类，创建 EventRunner，并创建 EventHandler 子类的实例，步骤与[ EventHandler 投递 InnerEvent] 场景的步骤1-3相同。

1. 创建 Runnable 任务。

   Runnable task1 = new Runnable() {
       @Override
       public void run() {
           // 待执行的操作，由开发者定义
       }
   };
   Runnable task2 = new Runnable() {
       @Override
       public void run() {
           // 待执行的操作，由开发者定义
       }
   };

1. 投递 Runnable 任务，投递的优先级以 IMMEDIATE 为例，延时选择 0ms 和 2ms。

   //优先级为 immediate，延时 0ms，该语句等价于同步投递myHandler.postSyncTask(task1，EventHandler.Priority.immediate);
   myHandler.postTask(task1，0， EventHandler.Priority.IMMEDIATE);

    
   myHandler.postTask(task2，2， EventHandler.Priority.IMMEDIATE);// 延时2ms后立即执行

1. 启动和停止 EventRunner，如果是托管模式，则不需要此步骤。

   runner.run();
   //待执行操作

    
   runner.stop();// 停止 EventRunner

在新创建的线程里投递事件到原线程

EventHandler 从新创建的线程投递事件到原线程并进行处理，开发步骤如下：

1. 创建 EventHandler 的子类，在子类中重写实现方法 processEvent() 来处理事件。

   private class MyEventHandler extends EventHandler {
       private MyEventHandler(EventRunner runner) {
       super(runner);
       }
       // 重写实现processEvent方法
       @Override
       public void processEvent(InnerEvent event) {
       super.processEvent(event);
       if (event == null) {
               return;
       }
       int eventId = event.eventId;
       long param = event.param;
           Object object = event.object;
       switch (eventId | param) {
               case CASE1:
                   // 待执行的操作，由开发者定义
               break;
               case CASE2:
                   // 将原先线程的EventRunner实例投递给新创建的线程
                   if (object instanceof EventRunner) {
                   EventRunner runner2 = (EventRunner)object;
                   }
                   // 将原先线程的EventRunner实例与新创建的线程的EventHandler绑定
                   EventHandler myHandler2 = new EventHandler(runner2) {
                   @Override
                   public void processEvent(InnerEvent event) {
                  //需要在原先线程执行的操作
                   }
                   };
                   int eventId = 1; 
                   long param = 0; 
                   Object object = null; 
                   InnerEvent event2 = InnerEvent.get(eventId, param, object);
                   myHandler2.sendEvent(event2); // 投递事件到原先的线程
                   break;
           default:
           break;
       }
       }
   }

1. 创建 EventRunner，以手动模式为例。

   EventRunner runner1 = EventRunner.create(false);// create()的参数是true时，则为托管模式。
   // 需要对 EventRunner 的实例进行校验，不是任何线程都可以通过 create 创建，例如：当线程池已满时，不能再创建线程。
   if (runner1 == null) {
       return;
   }

1. 创建 EventHandler 子类的实例。

   MyEventHandler myHandler1 = new MyEventHandler(runner1);

1. 获取 InnerEvent 事件。

   // 获取事件实例，其属性 eventId, param, object 由开发者确定，代码中只是示例。
   int eventId1 = 0;
   long param = 0; 
   Object object = (Object) EventRunner.current();
   InnerEvent event1 = InnerEvent.get(eventId1, param, object);

1. 投递事件，在新线程上直接处理。

   // 将与当前线程绑定的 EventRunner 投递到与 runner1 创建的新线程中  myHandler.sendEvent(event1);

1. 启动和停止 EventRunner，如果是托管模式，则不需要此步骤。

   runner.run();
   //待执行操作

    
   runner.stop();// 停止 EventRunner

完整代码示例

• 非托管情况：

  //全局：
  EventRunner runnerA

   
  //线程A：
  runnerA = EventRunner.create(false);
  runnerA.run(); // run之后一直循环卡在这里，所以需要新建一个线程run

   
  //线程B：
  //1.创建类继承EventHandler
  public class MyEventHandler extends EventHandler {
      public static int CODE_DOWNLOAD_FILE1;
      public static int CODE_DOWNLOAD_FILE2;
      public static int CODE_DOWNLOAD_FILE3;
      private MyEventHandler(EventRunner runner) {
          super(runner);
      }

   
      @Override
      public void processEvent(InnerEvent event) {
          super.processEvent(event);
          if (event == null) {
              return;
          }

   
          int eventId = event.eventId;
          if (STOP_EVENT_ID != eventId) {
              resultEventIdList.add(eventId);
          }

   
          switch (eventId) {
              case CODE_DOWNLOAD_FILE1: {
                  ... // your process
                  break;
              }
              case CODE_DOWNLOAD_FILE1: {
                  ... // your process
                  break;
              }
              case CODE_DOWNLOAD_FILE1: {
                  ... // your process
                  break;
              }
              default:
                  break;
          }
      }
  }

   
  //2.创建 MyEventHandler 实例
  MyEventHandler handler = new MyEventHandler(runnerA);

   
  // 3.向线程 A 发送事件
  handler.sendEvent(CODE_DOWNLOAD_FILE1);
  handler.sendEvent(CODE_DOWNLOAD_FILE2);
  handler.sendEvent(CODE_DOWNLOAD_FILE3);
  ......

   
  // 4.runnerA 不再使用后，退出
  runnerA.stop();

• 托管情况：

  //1.创建 EventRunner A：
  EventRunner runnerA = EventRunner.create("downloadRunner"); // 内部会新建一个线程

   
  //2.创建类继承 EventHandler
  public class MyEventHandler extends EventHandler {
      public static int CODE_DOWNLOAD_FILE1;
      public static int CODE_DOWNLOAD_FILE2;
      public static int CODE_DOWNLOAD_FILE3;
      private MyEventHandler(EventRunner runner) {
          super(runner);
      }

   
      @Override
      public void processEvent(InnerEvent event) {
          super.processEvent(event);
          if (event == null) {
              return;
          }

   
          int eventId = event.eventId;
          if (STOP_EVENT_ID != eventId) {
              resultEventIdList.add(eventId);
          }

   
          switch (eventId) {
              case CODE_DOWNLOAD_FILE1: {
                  ... // your process
                  break;
              }
              case CODE_DOWNLOAD_FILE1: {
                  ... // your process
                  break;
              }
              case CODE_DOWNLOAD_FILE1: {
                  ... // your process
                  break;
              }
              default:
                  break;
          }
      }
  }

   
  //3.创建MyEventHandler实例
  MyEventHandler handler = new MyEventHandler(runnerA);

   
  //4.向线程A发送事件
  handler.sendEvent(CODE_DOWNLOAD_FILE1);
  handler.sendEvent(CODE_DOWNLOAD_FILE2);
  handler.sendEvent(CODE_DOWNLOAD_FILE3);
  ......

   
  //5.runnerA没有任何对象引入时，线程会自动回收
  runnerA = null;