Using Emitter for Inter-Thread Communication

Emitter is an event processing mechanism used in a process. It provides the capabilities of subscribing to, publishing, and unsubscribing from events for applications.

When to Use

Emitter is used to process events of the same thread or different threads in the same process in an asynchronous manner. To use this mechanism, you need to subscribe to an event and publish it, after which the Emitter distributes the published event to the subscriber, and the subscriber executes the callback method set during event subscription. Unsubscribe from the event in time to release the Emitter resources when the event does not need to be subscribed to.

Working Principles

Emitter distributes tasks by maintaining an internal event queue. An application needs to subscribe to an event and set the callback method of the event. After the application publishes the event, an event is inserted into the queue. The task queue executes the tasks serially, during which the callback method of the task subscriber is called to process the event.

Available APIs

For details, see @ohos.events.emitter (Emitter).

API	Capability	Description
on	Event subscription	Continuously subscribes to an event until the event is unsubscribed from.
once	Event subscription	Subscribes to an event once.
emit	Event publishing	Publishes an event once.
off	Event unsubscription	Unsubscribes from the event and subsequent notifications of this event will not be received.

How to Develop

To enable Emitter's capabilities mentioned above, perform the following steps:

1. Import the related modules.

   import { emitter, Callback } from '@kit.BasicServicesKit';
   

   Index.ets

2. Subscribe to an event.

   Use on() for continuous subscription or once() for one-time subscription. Set the events to subscribe to and the callback function after the events are received.

   // Define an event with eventId 1.
   let event: emitter.InnerEvent = {
     eventId: 1
   };
   // Define a callback for an event.
   let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
     this.messageOn = eventData.data!.content
     console.info(`eventData: ${JSON.stringify(eventData)}`);
   }
   // ···
   // Execute the callback after receiving the event whose eventId is 1.
   emitter.on(event, callback);
   

   Index.ets

   // Execute the callback after receiving the event whose eventId is 1.
   // Note that the event is received only once using once(), while the event is received until the subscription is canceled using on().
   emitter.once(event, callback);
   

   Index.ets

3. Emit the event.

   Use emit() to emit events and set the events to send and the parameters to pass.

   NOTE

   • This API can be used to emit data objects across threads. The data objects must meet the specifications specified in Overview of Inter-Thread Communication Objects. Currently, complex data decorated by decorators such as @State and @Observed is not supported.
   • After an event is published using the emit API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event.

   // Define an event with eventId 1 and priority Low.
   let event: emitter.InnerEvent = {
     eventId: 1,
     priority: emitter.EventPriority.LOW
   };
   
   let eventData: emitter.EventData = {
     data: {
       content: 'emitter',
       id: 1,
       isEmpty: false
     }
   };
   
   // Emit the event with eventId 1 and event content eventData.
   emitter.emit(event, eventData);
   

   Index.ets

4. Unsubscribe from the event.

   NOTE

   • If an event does not need to be subscribed to, cancel the subscription in a timely manner to prevent memory leakage.
   • After the off API is used to unsubscribe from an event, the event that has been published through the emit API but has not been executed will be unsubscribed.

   // Unsubscribe from the event with eventId 1.
   emitter.off(1);
   

   Index.ets