1
0
mirror of https://github.com/lensapp/lens.git synced 2025-05-20 05:10:56 +00:00

some more doc fixes

Signed-off-by: Sebastian Malton <sebastian@malton.name>
This commit is contained in:
Sebastian Malton 2021-05-21 14:55:48 -04:00
parent 80e6df50f2
commit 9506aeda38

View File

@ -1,10 +1,11 @@
# Inter Process Communication
A Lens Extension can utilize IPC to send information between its `LensRendererExtension` and its `LensMainExtension`.
A Lens Extension can utilize IPC to send information between the `renderer` and `main` processes.
This is useful when wanting to communicate directly within your extension.
For example, if a user logs into a service that your extension is a facade for and `main` needs to know some information so that you can start syncing items to the `Catalog`, this would be a good way to send that information along.
IPC channels are blocked off per extension.
IPC channels are sectioned off per extension.
Meaning that each extension can only communicate with itself.
## Types of Communication
@ -14,22 +15,22 @@ There are two flavours of communication that are provided:
- Event based (IPC)
- Request based (RPC)
### Event Based IPC
### Event Based or IPC
This is the same as an [Event Emitter](https://nodejs.org/api/events.html#events_class_eventemitter) but is not limited to just one Javascript process.
This is a good option when you need to report that something has happened but you don't need a response.
This is a fully two-way form of communication.
Both `LensMainExtension` and `LensRendererExtension` can do this sort of IPC.
Both `main` and `renderer` can do this sort of IPC.
### Request Based IPC
### Request Based or RPC
This is more like a Remote Procedure Call (RPC).
With this sort of IPC the caller waits for the result from the other side.
This is accomplished by returning a `Promise<T>` which needs to be `await`-ed.
This is more like a Remote Procedure Call (RPC) or Send-Receive-Reply (SRR).
With this sort of communication the caller needs to wait for the result from the other side.
This is accomplished by `await`-int the returned `Promise<any>`.
This is a unidirectional form of communication.
Only `LensRendererExtension` can initiate this kind of request, and only `LensMainExtension` can and respond this this kind of request.
Only `renderer` can initiate this kind of request, and only `main` can and respond this this kind of request.
## Registering IPC Handlers and Listeners
@ -75,7 +76,7 @@ function onInitialize(event: Types.IpcMainEvent, id: string) {
```
In other files, it is not necessary to pass around any instances.
It should be able to just call `getInstance()` everywhere in your extension as needed.
It should be able to just call `IpcMain.getInstance()` anywhere it is needed in your extension.
---
@ -109,13 +110,16 @@ It is necessary to create child classes of these `abstract class`'s in your exte
---
As this example shows: the channel names *must* be the same.
It should also be noted that "listeners" and "handlers" are specific to either `LensRendererExtension` and `LensMainExtension`.
It should also be noted that "listeners" and "handlers" are specific to either `renderer` or `main`.
There is no behind the scenes transfer of these functions.
If you want to register a "handler" you would call `IpcMain.getInstance().handle(...)` instead.
To register a "handler" call `IpcMain.getInstance().handle(...)`.
The cleanup of these handlers is handled by Lens itself.
Calling either `IpcRenderer.getInstance().broadcast(...)` or `IpcMain.getInstance().broadcast(...)` sends an event to all renderer frames and to main.
The `listen()` methods on `Ipc.Main` and `Ipc.Renderer` return a `Disposer`, or more specifically, a `() => void`.
This can be optionally called to remove the listener early.
Calling either `IpcRenderer.getInstance().broadcast(...)` or `IpcMain.getInstance().broadcast(...)` sends an event to all `renderer` frames and to `main`.
Because of this, no matter where you broadcast from, all listeners in `main` and `renderer` will be notified.
### Allowed Values
@ -123,6 +127,6 @@ Because of this, no matter where you broadcast from, all listeners in `main` and
This IPC mechanism utilizes the [Structured Clone Algorithm](developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) for serialization.
This means that more types than what are JSON serializable can be used, but not all the information will be passed through.
## Using RPC
## Using Request Based Communication
If you are meaning to do a request based call from `renderer`, you should do `const res = await IpcRenderer.getInstance().invoke(<channel>, ...<args>));` instead.