1# Using Emitter for Inter-Thread Communication
2
3
4Emitter is an event processing mechanism used in a process. It provides the capabilities of subscribing to, publishing, and unsubscribing from events for applications.
5
6## When to Use
7
8Emitter 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.
9
10## Working Principles
11Emitter 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 publish the event, an event is inserted into the queue. The task queue executes the tasks in serial mode, during which the callback method of the task subscriber is called to process the event.
12
13![emitter](figures/emitter.png)
14
15## Available APIs
16For details, see [@ohos.events.emitter (Emitter)](../../reference/apis-basic-services-kit/js-apis-emitter.md).
17| API | Capability  | Description    |
18| ------- | ------ | -------- |
19| on | Event subscription| Continuously subscribes to an event until the event is unsubscribed from.|
20| once | Event subscription| Subscribes to an event once.|
21| emit | Event publishing| Publishes an event once.|
22| off | Event unsubscription.| Unsubscribes from the event and subsequent notifications of this event will not be received.|
23
24## How to Develop
25
26To enable Emitter's capabilities mentioned above, perform the following steps:
27
281. Import the Emitter module.
29
30   ```ts
31   import { emitter } from '@kit.BasicServicesKit';
32   ```
33
342. Subscribe to an event.
35
36   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.
37   ```ts
38    // Define an event with eventId 1.
39    let event: emitter.InnerEvent = {
40      eventId: 1
41    };
42
43    // Use on() to subscribe to the event. After the event whose eventId is 1 is received, the callback function is executed.
44    emitter.on(event, () => {
45      console.info('on callback');
46    });
47   ```
48
49   ```ts
50   // Execute the callback after receiving the event whose eventId is 1.
51   // Note that the event is received only once using once(), while the event is received until the subscription is canceled using on().
52   emitter.once(event, () => {
53     console.info('once callback');
54   });
55   ```
56
573. Emit the event.
58
59   Use **emit()** to send events and set the events to send and the parameters to pass.
60   ```ts
61   // Define an event with eventId 1 and priority Low.
62   let event: emitter.InnerEvent = {
63     eventId: 1,
64     priority: emitter.EventPriority.LOW
65   };
66
67   // Subscribes to the event and receive eventData.
68   emitter.once(event, (eventData : emitter.EventData) => {
69     console.info('enter callback, eventData-content:' + eventData?.data?.content);
70     console.info('enter callback, eventData-id:' + eventData?.data?.id);
71     console.info('enter callback, eventData-isEmpty:' + eventData?.data?.isEmpty);
72   });
73
74   let eventData: emitter.EventData = {
75     data: {
76       content: 'emitter',
77       id: 1,
78       isEmpty: false
79     }
80   };
81
82   // Emit the event with eventId 1 and event content eventData.
83   emitter.emit(event, eventData);
84   ```
85
864. Unsubscribe from the event.
87    > **NOTE**
88    >
89    > If an event does not need to be subscribed to, cancel the subscription in a timely manner to prevent memory leakage.
90
91    Use **off()** to unsubscribe from the event and set the corresponding event ID.
92   ```ts
93   // Unsubscribe from the event with eventId 1.
94   emitter.off(1);
95   ```
96