From d97fc0f67ae741a814d9432ac4841d4ce3439913 Mon Sep 17 00:00:00 2001 From: "Maarten A. Breddels" Date: Tue, 11 Jan 2022 12:34:44 +0100 Subject: [PATCH 1/2] document protocol version 2.1.0 --- packages/base/src/version.ts | 2 +- packages/schema/messages.md | 25 ++++++++++++++++++++++++ python/ipywidgets/ipywidgets/_version.py | 2 +- 3 files changed, 27 insertions(+), 2 deletions(-) diff --git a/packages/base/src/version.ts b/packages/base/src/version.ts index d1e617d5bd..3897463d6f 100644 --- a/packages/base/src/version.ts +++ b/packages/base/src/version.ts @@ -3,4 +3,4 @@ export const JUPYTER_WIDGETS_VERSION = '2.0.0'; -export const PROTOCOL_VERSION = '2.0.0'; +export const PROTOCOL_VERSION = '2.1.0'; diff --git a/packages/schema/messages.md b/packages/schema/messages.md index 5cabf449bd..8d98c5759f 100644 --- a/packages/schema/messages.md +++ b/packages/schema/messages.md @@ -292,6 +292,31 @@ The `data.state` and `data.buffer_paths` values are the same as in the `comm_ope See the [Model state](jupyterwidgetmodels.latest.md) documentation for the attributes of core Jupyter widgets. +#### Synchronizing multiple frontends: `update` with echo + +Starting with protocol version `2.1.0` the kernel can send a special update message back, to allow all connected frontends to be in sync with the kernel state. This allows multiple frontends to be connected to a single kernel but also resolves a possible out of sync situation when the kernel and a frontend send out an update message at the same time, causing both to think they have the latest state. + +In protocol version `2.1.0` the kernel is considered the single source of truth and is expected to send back to the frontends an update message that contains an extra list of keys to indicate which keys in the update are send back to the frontends as a reaction to an update received from a frontend. + +``` +{ + 'comm_id' : 'u-u-i-d', + 'data' : { + 'method': 'update', + 'state': { }, + 'buffer_paths': [ ] + 'echo': [ ] + } +} +``` + +In situations where a user does many changes to a widget on the frontend (e.g. moving a slider), the frontend will receive from the kernel many update messages (with the echo key set) from the kernel that can be considered old values. A frontend can choose to ignore all updates that are not originating from the last update it send to the kernel. This can be implemented by keeping track of the `msg_id` for each attribyte for which we send out an update message to the kernel, and ignoring all updates as a result from an `echo` for which the [`msg_id` of the parent header](https://jupyter-client.readthedocs.io/en/latest/messaging.html#parent-header) is not equal to `msg_id` we kept track of. + +For situations where sending back an echo update for a property is considered to expensive, we have implemented an opt-out mechanism in ipywidgets. A trait can have a `no_echo` metadata attribute to flag that the kernel should not send back an update to the frontends. We suggest other implementations implement a similar opt-out mechanism. + +Note that this change is backwards compatible for frontends that implement version `2.0.0` since they will see these new update messages as a normal update message. Also, a frontend that implements version `2.1.0` but a kernel that does not send back echo updates will simply operate as a in version `2.0.0`, since it will only receive normal update messages. + + #### State requests: `request_state` When a frontend wants to request the full state of a widget, the frontend sends a `request_state` message: diff --git a/python/ipywidgets/ipywidgets/_version.py b/python/ipywidgets/ipywidgets/_version.py index ea1b267b20..4c0c1ca148 100644 --- a/python/ipywidgets/ipywidgets/_version.py +++ b/python/ipywidgets/ipywidgets/_version.py @@ -3,7 +3,7 @@ __version__ = '8.0.0b1' -__protocol_version__ = '2.0.0' +__protocol_version__ = '2.1.0' __control_protocol_version__ = '1.0.0' # These are *protocol* versions for each package, *not* npm versions. To check, look at each package's src/version.ts file for the protocol version the package implements. From 9b70ce9aed22060e5b7b2249f23150ee654ad1e7 Mon Sep 17 00:00:00 2001 From: Sylvain Corlay Date: Tue, 18 Jan 2022 19:05:04 +0100 Subject: [PATCH 2/2] Bump protocol version to 3.0 --- packages/base-manager/test/src/manager_test.ts | 4 ++-- packages/base/src/version.ts | 2 +- packages/schema/messages.md | 7 ++----- python/ipywidgets/ipywidgets/_version.py | 2 +- 4 files changed, 6 insertions(+), 9 deletions(-) diff --git a/packages/base-manager/test/src/manager_test.ts b/packages/base-manager/test/src/manager_test.ts index 45793bc05e..d913b982ca 100644 --- a/packages/base-manager/test/src/manager_test.ts +++ b/packages/base-manager/test/src/manager_test.ts @@ -168,7 +168,7 @@ describe('ManagerBase', function () { }, }, metadata: { - version: '2.0.0', + version: '3.0.0', }, }); expect(model.comm).to.equal(comm); @@ -231,7 +231,7 @@ describe('ManagerBase', function () { }, buffers: [new DataView(new Uint8Array([1, 2, 3]).buffer)], metadata: { - version: '2.0.0', + version: '3.0.0', }, }); expect(model.comm).to.equal(comm); diff --git a/packages/base/src/version.ts b/packages/base/src/version.ts index 3897463d6f..5249af2cd2 100644 --- a/packages/base/src/version.ts +++ b/packages/base/src/version.ts @@ -3,4 +3,4 @@ export const JUPYTER_WIDGETS_VERSION = '2.0.0'; -export const PROTOCOL_VERSION = '2.1.0'; +export const PROTOCOL_VERSION = '3.0.0'; diff --git a/packages/schema/messages.md b/packages/schema/messages.md index 8d98c5759f..af144a29f7 100644 --- a/packages/schema/messages.md +++ b/packages/schema/messages.md @@ -294,9 +294,9 @@ See the [Model state](jupyterwidgetmodels.latest.md) documentation for the attri #### Synchronizing multiple frontends: `update` with echo -Starting with protocol version `2.1.0` the kernel can send a special update message back, to allow all connected frontends to be in sync with the kernel state. This allows multiple frontends to be connected to a single kernel but also resolves a possible out of sync situation when the kernel and a frontend send out an update message at the same time, causing both to think they have the latest state. +Starting with protocol version `3.0.0` the kernel can send a special update message back, to allow all connected frontends to be in sync with the kernel state. This allows multiple frontends to be connected to a single kernel but also resolves a possible out of sync situation when the kernel and a frontend send out an update message at the same time, causing both to think they have the latest state. -In protocol version `2.1.0` the kernel is considered the single source of truth and is expected to send back to the frontends an update message that contains an extra list of keys to indicate which keys in the update are send back to the frontends as a reaction to an update received from a frontend. +In protocol version `3.0.0` the kernel is considered the single source of truth and is expected to send back to the frontends an update message that contains an extra list of keys to indicate which keys in the update are send back to the frontends as a reaction to an update received from a frontend. ``` { @@ -314,9 +314,6 @@ In situations where a user does many changes to a widget on the frontend (e.g. m For situations where sending back an echo update for a property is considered to expensive, we have implemented an opt-out mechanism in ipywidgets. A trait can have a `no_echo` metadata attribute to flag that the kernel should not send back an update to the frontends. We suggest other implementations implement a similar opt-out mechanism. -Note that this change is backwards compatible for frontends that implement version `2.0.0` since they will see these new update messages as a normal update message. Also, a frontend that implements version `2.1.0` but a kernel that does not send back echo updates will simply operate as a in version `2.0.0`, since it will only receive normal update messages. - - #### State requests: `request_state` When a frontend wants to request the full state of a widget, the frontend sends a `request_state` message: diff --git a/python/ipywidgets/ipywidgets/_version.py b/python/ipywidgets/ipywidgets/_version.py index 4c0c1ca148..a16e0486e4 100644 --- a/python/ipywidgets/ipywidgets/_version.py +++ b/python/ipywidgets/ipywidgets/_version.py @@ -3,7 +3,7 @@ __version__ = '8.0.0b1' -__protocol_version__ = '2.1.0' +__protocol_version__ = '3.0.0' __control_protocol_version__ = '1.0.0' # These are *protocol* versions for each package, *not* npm versions. To check, look at each package's src/version.ts file for the protocol version the package implements.