1# Using Emitter for Inter-Thread Communication 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: Notification--> 5<!--Owner: @peixu--> 6<!--Designer: @dongqingran; @wulong158--> 7<!--Tester: @wanghong1997--> 8<!--Adviser: @huipeizi--> 9 10Emitter is an event processing mechanism used in a process. It provides the capabilities of subscribing to, publishing, and unsubscribing from events for applications. 11 12## When to Use 13 14Emitter 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. 15 16## Working Principles 17Emitter 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. 18 19 20 21## Available APIs 22For details, see [@ohos.events.emitter (Emitter)](../../reference/apis-basic-services-kit/js-apis-emitter.md). 23| API | Capability | Description | 24| ------- | ------ | -------- | 25| on | Event subscription| Continuously subscribes to an event until the event is unsubscribed from.| 26| once | Event subscription| Subscribes to an event once.| 27| emit | Event publishing| Publishes an event once.| 28| off | Event unsubscription.| Unsubscribes from the event and subsequent notifications of this event will not be received.| 29 30## How to Develop 31 32To enable Emitter's capabilities mentioned above, perform the following steps: 33 341. Import the Emitter module. 35 36 ```ts 37 import { emitter, Callback } from '@kit.BasicServicesKit'; 38 ``` 39 402. Subscribe to an event. 41 42 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. 43 ```ts 44 // Define an event with eventId 1. 45 let event: emitter.InnerEvent = { 46 eventId: 1 47 }; 48 // Define a callback for an event. 49 let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 50 console.info(`eventData: ${JSON.stringify(eventData)}`); 51 } 52 53 // Execute the callback after receiving the event whose eventId is 1. 54 emitter.on(event, callback); 55 ``` 56 57 ```ts 58 // Execute the callback after receiving the event whose eventId is 1. 59 // Note that the event is received only once using once(), while the event is received until the subscription is canceled using on(). 60 emitter.once(event, callback); 61 ``` 62 633. Emit the event. 64 65 Use **emit()** to send events and set the events to send and the parameters to pass. 66 > **NOTE** 67 > 68 > 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](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. 69 ```ts 70 // Define an event with eventId 1 and priority Low. 71 let event: emitter.InnerEvent = { 72 eventId: 1, 73 priority: emitter.EventPriority.LOW 74 }; 75 76 let eventData: emitter.EventData = { 77 data: { 78 content: 'emitter', 79 id: 1, 80 isEmpty: false 81 } 82 }; 83 84 // Emit the event with eventId 1 and event content eventData. 85 emitter.emit(event, eventData); 86 ``` 87 884. Unsubscribe from the event. 89 > **NOTE** 90 > 91 > - If an event does not need to be subscribed to, cancel the subscription in a timely manner to prevent memory leakage. 92 > - After the [off](../../reference/apis-basic-services-kit/js-apis-emitter.md#emitteroff) API is used to unsubscribe from an event, the event that has been published through the [emit](../../reference/apis-basic-services-kit/js-apis-emitter.md#emitteremit) API but has not been executed will be unsubscribed. 93 ```ts 94 // Unsubscribe from the event with eventId 1. 95 emitter.off(1); 96 ``` 97
