diff --git a/docs/API.en.pdf b/docs/API.en.pdf
index e8dc1f1..78526be 100644
Binary files a/docs/API.en.pdf and b/docs/API.en.pdf differ
diff --git a/docs/API.ru.epub b/docs/API.ru.epub
index 8babda2..7726bca 100644
Binary files a/docs/API.ru.epub and b/docs/API.ru.epub differ
diff --git a/docs/API.ru.html b/docs/API.ru.html
index 9b4162a..fc44a26 100644
--- a/docs/API.ru.html
+++ b/docs/API.ru.html
@@ -6610,7 +6610,7 @@ api.subscribe(
NB: следует различать Backend-Driven UI и технологию серверного рендеринга (SSR). Второе подразумевает, что одно и то же состояние UI (как правило, в виде HTML-разметки или аналогичного декларативного описания) может быть сгенерировано как сервером, так и клиентом. В SSR, однако, подразумевается, что клиент может интерпретировать ответ сервера и извлекать из него семантические данные.
С точки зрения предложения SDK сторонним разработчикам, Backend-Driven UI фактически вынуждает разрабатывать гибридный код (поскольку практика предоставления партнёрам возможности встроиться в функции серверного рендеринга на стороне провайдера API выглядит весьма далёкой от жизнеспособности идеей), и, таким образом, будет страдать от той же проблемы непрозрачности — разработчик не может со своей стороны определить, в каком сейчас состоянии находится визуальный компонент. Как ни странно, этот недостаток одновременно является и достоинством, поскольку вендор API сохраняет возможность на своей стороне производить любые манипуляции с контентом без нарушения обратной совместимости (мы обсудим этот вопрос в главе «Линейка сервисов API»). Таких клиентских API в мире существует довольно много (в первую очередь, разнообразные виджеты, рекламные API и т.д.), но их сложно назвать полноценными SDK.
-Другой важный паттерн, который мы должны рассмотреть — это доступ к общим ресурсам. Предположим, что в нашем учебном приложении открытие экрана предложения стало требовать выполнения дополнительного запроса к серверу и, таким образом, стало асинхронным. Модифицируем код OfferPanel:
+Другой важный паттерн, который мы должны рассмотреть — это доступ к общим ресурсам. Предположим, что в нашем учебном приложении открытие экрана предложения стало требовать выполнения дополнительного запроса к серверу и, таким образом, стало асинхронным. Модифицируем код OfferPanelComponent:
class OfferPanelComponent {
…
show (offer) {
@@ -6640,12 +6640,12 @@ api.subscribe(
constructor () {
…
this.offerPanel.events.on(
- 'beginFullDataLoad', () => {
+ 'beginDataLoad', () => {
this.isDataLoading = true;
}
);
this.offerPanel.events.on(
- 'endFullDataLoad', () => {
+ 'endDataLoad', () => {
this.isDataLoading = false;
}
);
@@ -6661,11 +6661,15 @@ api.subscribe(
Но этот код очень плох по множеству причин:
-- непонятно, как его модифицировать, если у нас появятся разные виды загрузок данных, причём некоторые из них будут требовать блокировки прокрутки, а некоторые — нет;
-- этот код просто плохо читается: совершенно непонятно, почему события анимации на одном компоненте влияют на прокрутку в другом компоненте;
-- если при выполнении анимации произойдёт какая-то ошибка, событие
endAnimation не произойдёт и прокрутка будет заблокирована навсегда.
+- непонятно, как его модифицировать, если у нас появятся разные виды загрузок данных, причём некоторые из них будут требовать блокировки интерфейса, а некоторые — нет;
+- этот код просто плохо читается: совершенно непонятно, почему события загрузки данных на одном компоненте влияют на пользовательскую функциональность в другом компоненте;
+- если при загрузке произойдёт какая-то ошибка, событие
endDataLoad не произойдёт, и интерфейс останется заблокированным навсегда.
+
+Если вы внимательно читали предыдущие главы, решение этих двух проблем должен быть очевидным. Необходимо абстрагироваться от самого факта загрузки данных и переформулировать проблемы в высокоуровневых терминах. У нас есть разделяемый ресурс — место на экране. Мы можем показывать в один момент времени только одно предложение. Следовательно, если какому-то актору требуется длящийся доступ к панели, он должен этот доступ явно получить. Отсюда следует, что:
+
+- флаг такого доступа должен именоваться явно (например,
offerFullViewLocked, а не isDataLoading);
+- флаг контролироваться
Composer-ом, но никак не самой панелью предложения (ещё и потому, что подготовка данных для показа — также ответственность Composer-а).
-Если вы внимательно читали предыдущие главы, решение этих двух проблем должен быть очевидным. Необходимо абстрагироваться от самого факта анимации и переформулировать проблемы в высокоуровневых терминах. У нас есть разделяемый ресурс — место на экране. Мы можем показывать в один момент времени только одно предложение. Следовательно, если какому-то актору требуется длящийся доступ к панели, он должен этот доступ явно получить. Отсюда следует, что, во-первых, флаг такого доступа должен именоваться явно (например, offerFullViewLocked, а не isDataLoading) и контролироваться Composer-ом, но никак не самой панелью предложения (ещё и потому, что подготовка данных для показа — также ответственность Composer-а).
class SearchBoxComposer {
constructor () {
…
@@ -6718,7 +6722,7 @@ api.subscribe(
}
}
-NB: вторым параметром в acquireLock мы передали максимальное время жизни блокировки — 10 секунд. Если в течение этого времени блокировка не снята (например, в случае, если ), она будет отменена автоматически.
+NB: вторым параметром в acquireLock мы передали максимальное время жизни блокировки — 10 секунд. Если в течение этого времени блокировка не снята (например, в случае, если мы забыли обработать какое-то исключение или выставить таймаут на запрос к серверу), она будет отменена автоматически, и интерфейс будет разблокирован.
В таком подходе мы можем реализовать не только блокировки, но и различные сценарии, которые позволяют нам более гибко ими управлять. Добавим в функцию захвата ресурса дополнительные данные о целях захвата:
lock = this.acquireLock(
'offerFullView', '10s', {
@@ -6730,7 +6734,7 @@ api.subscribe(
}
);
-Тогда текущий владелец ресурса (или диспетчер блокировок) может, в зависимости от ситуации, отдавать владение ресурсом или, наоборот, запрещать перехват. Скажем, если открытие панели инициировано программистом через вызов API компонента (а не пользователем через выбор предложения в списке), оно может иметь более высокий приоритет и быть разрешено:
+Тогда текущий владелец ресурса (или диспетчер блокировок, если мы реализуем такой объект) может, в зависимости от ситуации, отдавать владение ресурсом или, наоборот, запрещать перехват. Скажем, если открытие панели инициировано программистом через вызов API компонента (а не пользователем через выбор предложения в списке), оно может иметь более высокий приоритет и быть разрешено:
lock.events.on('tryAcquire', (actor) => {
if (sender.reason == 'apiSelectOffer') {
lock.release();
@@ -6742,7 +6746,7 @@ api.subscribe(
Дополнительно мы можем ввести и обработку потери контроля ресурса — например, отменить загрузку данных, которые больше не нужны.
lock.events.on('lost', () => {
- this.cancelFullDataLoad();
+ this.cancelFullOfferDataLoad();
})
Паттерн контроля разделяемых ресурсов также хорошо сочетается с паттерном «модель»: акторы могут захватывать доступ на чтение и/или изменение свойств или групп свойств модели.
@@ -6750,9 +6754,9 @@ api.subscribe(
- открыть панель предложения;
- вместо настоящих данных отобразить спиннер или какую-то другую индикацию загрузки;
-- асинхронно обновить отображение при получении ответа от сервера.
-Однако в постановке проблемы это ничего не меняет: нам всё ещё нужно разработать политику разрешения конфликтов для случая, если какой-то актор пытается открыть панель предложения, пока загрузка данных ещё не закончена, для чего нам вновь нужны разделяемые ресурсы и их захват.
+- асинхронно обновить отображение при получении ответа от сервера.
+Однако в постановке проблемы это ничего не меняет: нам всё ещё нужно разработать политику разрешения конфликтов для случая, если какой-то актор пытается открыть панель предложения, пока загрузка данных ещё не закончена, для чего нам вновь нужны разделяемые ресурсы и их захват.
Отметим, что в современном фронтенде (к нашему большому сожалению) подобные упражнения с захватом контроля на время загрузки данных или анимации компонентов практически не производятся (считается, что такие асинхронные операции происходят быстро, и коллизии доступа не представляют собой проблемы). Однако, если асинхронные операции выполняются долго (происходят длительные или многоступенчатые загрузки данных, сложные анимации), пренебрежение организацией доступа может быть очень серьёзной UX-проблемой.
Когда мы говорим об API как о продукте, необходимо чётко зафиксировать два важных тезиса.
diff --git a/docs/API.ru.pdf b/docs/API.ru.pdf
index 4ef0bfa..adaac66 100644
Binary files a/docs/API.ru.pdf and b/docs/API.ru.pdf differ
diff --git a/docs/index.html b/docs/index.html
index c655a8d..34cd214 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -131,7 +131,7 @@
- Chapter 44. Decomposing UI Components
- Chapter 45. The MV* Frameworks
- Chapter 46. The Backend-Driven UI
-- Chapter 47. Shared Resources and Asynchronous Locks
+- Chapter 47. Shared Resources and Asynchronous Locks
- Chapter 48. Computed Properties
- Chapter 49. Conclusion
diff --git a/src/en/clean-copy/06-[Work in Progress] Section V. SDKs & UI Libraries/07.md b/src/en/clean-copy/06-[Work in Progress] Section V. SDKs & UI Libraries/07.md
index 3ead19c..d6c41b9 100644
--- a/src/en/clean-copy/06-[Work in Progress] Section V. SDKs & UI Libraries/07.md
+++ b/src/en/clean-copy/06-[Work in Progress] Section V. SDKs & UI Libraries/07.md
@@ -1 +1,172 @@
-### Shared Resources and Asynchronous Locks
\ No newline at end of file
+### [Shared Resources and Asynchronous Locks][sdk-shared-resources]
+
+Another important pattern we need to discuss is accessing shared resources. Imagine that in our study application, opening an offer panel required making an additional request to the server and thus became asynchronous. Let's modify the `OfferPanelComponent` code:
+
+```typescript
+class OfferPanelComponent {
+ …
+ show (offer) {
+ let fullData = await api
+ .getFullOfferData(offer);
+ …
+ }
+}
+```
+
+A question arises: what should happen if the user or the developers tries to select another `offerId` while the server response for the previous one hasn't been received yet? Obviously, we must choose which of the two openings needs to be suppressed. Let's say we decided to block the interface during the data load and by doing so, prohibit selecting another offer. To implement this functionality, we need to notify parent components about data requests being initiated or fulfilled:
+
+```typescript
+class OfferPanelComponent {
+ …
+ show () {
+ /* */this.events.emit('beginDataLoad');/* */
+ let fullData = await api
+ .getFullOfferData(offer);
+ /* */this.events.emit('endDataLoad');/* */
+ …
+ }
+}
+```
+
+```typescript
+// `Composer` listens to the panel events
+// and sets the value of the
+// corresponding flag
+class SearchBoxComposer {
+ …
+ constructor () {
+ …
+ this.offerPanel.events.on(
+ 'beginDataLoad', () => {
+ /* */this.isDataLoading = true;/* */
+ }
+ );
+ this.offerPanel.events.on(
+ 'endDataLoad', () => {
+ /* */this.isDataLoading = false;/* */
+ }
+ );
+ }
+
+ selectOffer (offer) {
+ if (this.isDataLoading) {
+ return;
+ }
+ …
+ }
+}
+```
+
+However, this code is flawed for several reasons:
+ * There is no obvious way to modify it if different types of data loads occur, and some of them require blocking the UI while others do not.
+ * It is poorly readable because it is rather difficult to comprehend why data load events on one component affect the user-facing functionality of the other component.
+ * If an exception is thrown while loading the data, the `endDataLoad` event will never happen and the interface will remain blocked indefinitely.
+
+If you have read the previous chapters thoroughly, the solution to these problems should be obvious. We need to abstract from the fact of loading data and reformulate the issue in high-level terms. We have a shared resource: the space on the screen. Only one offer can be displayed at a time. This means that every actor needing lasting access to the panel must explicitly obtain it. This entails two conclusions:
+ * The access flag must have an explicit name, such as `offerFullViewLocked`m and not `isDataLoading`.
+ * `Composer` must control this flag, not the offer panel itself (additionally, because preparing data for displaying in the panel is `Composer`'s responsibility).
+
+```typescript
+class SearchBoxComposer {
+ constructor () {
+ …
+ this.offerFullViewLocked = false;
+ }
+ …
+ selectOffer (offer) {
+ if (this.offerFullViewLocked) {
+ return;
+ }
+ this.offerFullViewLocked = true;
+ let fullData = await api
+ .getFullOfferData(offer);
+ this.events.emit(
+ 'offerFullViewChange',
+ this.generateOfferFullView(fullData)
+ );
+ this.offerFullViewLocked = false;
+ }
+}
+```
+
+This approach improves readability but doesn't help with parallel access and error recovery. To address these issues, we must take the next step: not just create a flag but introduce a procedure for *capturing* it (quite classically, similar to managing exclusive access to shared resources in system programming):
+
+```typescript
+class SearchBoxComposer {
+ …
+ selectOffer (offer) {
+ let lock;
+ try {
+ // Trying to catpture the
+ // `offerFullView` resource
+ lock = this.acquireLock(
+ 'offerFullView', '10s'
+ );
+ let fullData = await api
+ .getFullOfferData(offer);
+ this.events.emit(
+ 'offerFullViewChange',
+ this.generateOfferFullView(fullData)
+ );
+ lock.release();
+ } catch (e) {
+ // If we were unable to get access
+ return;
+ } finally {
+ // Don't forget to free the resource
+ // in the case of an exception
+ if (lock) {
+ lock.release();
+ }
+ }
+ }
+}
+```
+
+**NB**: the second argument to the `acquireLock` function is the lock's lifespan (10 seconds, in our case). This implies that the lock will be automatically released after this timeout has passed (which is useful in case we have forgotten to catch an exception or set a timeout for a data load request), thus unblocking the UI.
+
+With this approach, we can implement not only locks, but also various scenarios to flexibly manage them. Let's add data regarding the acquirer in the lock function:
+
+```typescript
+lock = this.acquireLock(
+ 'offerFullView', '10s', {
+ // Who is trying to acquire a lock
+ // and for what reason
+ reason: 'userSelectOffer',
+ offer
+ }
+);
+```
+
+Then the current lock holder (or a lock dispatcher, if we implement it) could either relinquish control over the resource or prevent interception depending on the situation. For example, if opening the panel is initiated by the developer by calling an API method (rather than a user selecting another offer from the list), we could prioritize it and grant it the right to seize control:
+
+```typescript
+lock.events.on('tryAcquire', (actor) => {
+ if (sender.reason == 'apiSelectOffer') {
+ lock.release();
+ } else {
+ // Otherwise, prevent interception
+ // of the lock
+ return false;
+ }
+})
+```
+
+Additionally, we might add a handler to react to losing control — for example, to cancel the request for data if it is no longer needed:
+
+```typescript
+lock.events.on('lost', () => {
+ this.cancelFullOfferDataLoad();
+})
+```
+
+The shared resource access control partner aligns well with the “model” pattern: actors can acquire read and/or write locks for specific data fields (or groups of fields) of the model.
+
+**NB**: we could have addressed the data load problem differently:
+ * Open the offer panel
+ * Display a spinner or a placeholder instead of the real data
+ * Asynchronously update the view once the data is loaded.
+
+However, this doesn't change the problem definition: we still need a conflict resolution policy if another actor attempts to open the panel while the data is still loading, and for this we need shared resources and mechanisms for gaining exclusive access to them.
+
+Regrettably, in modern frontend development, such techniques involving taking control over UI elements while data is loading or animations are being performed are rarely used. Such asynchronous operations are considered fast enough to not be concerned about access collisions. However, if latencies are high (e.g., complex or multi-staged requests or animations occur), neglecting access management could be a major UX problem.
\ No newline at end of file
diff --git a/src/ru/clean-copy/06-[В разработке] Раздел V. SDK и UI-библиотеки/07.md b/src/ru/clean-copy/06-[В разработке] Раздел V. SDK и UI-библиотеки/07.md
index 371ddaf..bba08d4 100644
--- a/src/ru/clean-copy/06-[В разработке] Раздел V. SDK и UI-библиотеки/07.md
+++ b/src/ru/clean-copy/06-[В разработке] Раздел V. SDK и UI-библиотеки/07.md
@@ -1,6 +1,6 @@
### [Разделяемые ресурсы и асинхронные блокировки][sdk-shared-resources]
-Другой важный паттерн, который мы должны рассмотреть — это доступ к общим ресурсам. Предположим, что в нашем учебном приложении открытие экрана предложения стало требовать выполнения дополнительного запроса к серверу и, таким образом, стало асинхронным. Модифицируем код `OfferPanel`:
+Другой важный паттерн, который мы должны рассмотреть — это доступ к общим ресурсам. Предположим, что в нашем учебном приложении открытие экрана предложения стало требовать выполнения дополнительного запроса к серверу и, таким образом, стало асинхронным. Модифицируем код `OfferPanelComponent`:
```typescript
class OfferPanelComponent {
@@ -37,12 +37,12 @@ class SearchBoxComposer {
constructor () {
…
this.offerPanel.events.on(
- 'beginFullDataLoad', () => {
+ 'beginDataLoad', () => {
/* */this.isDataLoading = true;/* */
}
);
this.offerPanel.events.on(
- 'endFullDataLoad', () => {
+ 'endDataLoad', () => {
/* */this.isDataLoading = false;/* */
}
);
@@ -58,11 +58,13 @@ class SearchBoxComposer {
```
Но этот код очень плох по множеству причин:
- * непонятно, как его модифицировать, если у нас появятся разные виды загрузок данных, причём некоторые из них будут требовать блокировки прокрутки, а некоторые — нет;
- * этот код просто плохо читается: совершенно непонятно, почему события анимации на одном компоненте влияют на прокрутку в другом компоненте;
- * если при выполнении анимации произойдёт какая-то ошибка, событие `endAnimation` не произойдёт и прокрутка будет заблокирована навсегда.
+ * непонятно, как его модифицировать, если у нас появятся разные виды загрузок данных, причём некоторые из них будут требовать блокировки интерфейса, а некоторые — нет;
+ * этот код просто плохо читается: совершенно непонятно, почему события загрузки данных на одном компоненте влияют на пользовательскую функциональность в другом компоненте;
+ * если при загрузке произойдёт какая-то ошибка, событие `endDataLoad` не произойдёт, и интерфейс останется заблокированным навсегда.
-Если вы внимательно читали предыдущие главы, решение этих двух проблем должен быть очевидным. Необходимо абстрагироваться от самого факта анимации и переформулировать проблемы в высокоуровневых терминах. У нас есть разделяемый ресурс — место на экране. Мы можем показывать в один момент времени только одно предложение. Следовательно, если какому-то актору требуется длящийся доступ к панели, он должен этот доступ явно получить. Отсюда следует, что, во-первых, флаг такого доступа должен именоваться явно (например, `offerFullViewLocked`, а не `isDataLoading`) и контролироваться `Composer`-ом, но никак не самой панелью предложения (ещё и потому, что подготовка данных для показа — также ответственность `Composer`-а).
+Если вы внимательно читали предыдущие главы, решение этих двух проблем должен быть очевидным. Необходимо абстрагироваться от самого факта загрузки данных и переформулировать проблемы в высокоуровневых терминах. У нас есть разделяемый ресурс — место на экране. Мы можем показывать в один момент времени только одно предложение. Следовательно, если какому-то актору требуется длящийся доступ к панели, он должен этот доступ явно получить. Отсюда следует, что:
+ * флаг такого доступа должен именоваться явно (например, `offerFullViewLocked`, а не `isDataLoading`);
+ * флаг контролироваться `Composer`-ом, но никак не самой панелью предложения (ещё и потому, что подготовка данных для показа — также ответственность `Composer`-а).
```typescript
class SearchBoxComposer {
@@ -121,7 +123,7 @@ class SearchBoxComposer {
}
```
-**NB**: вторым параметром в `acquireLock` мы передали максимальное время жизни блокировки — 10 секунд. Если в течение этого времени блокировка не снята (например, в случае, если ), она будет отменена автоматически.
+**NB**: вторым параметром в `acquireLock` мы передали максимальное время жизни блокировки — 10 секунд. Если в течение этого времени блокировка не снята (например, в случае, если мы забыли обработать какое-то исключение или выставить таймаут на запрос к серверу), она будет отменена автоматически, и интерфейс будет разблокирован.
В таком подходе мы можем реализовать не только блокировки, но и различные сценарии, которые позволяют нам более гибко ими управлять. Добавим в функцию захвата ресурса дополнительные данные о целях захвата:
@@ -137,7 +139,7 @@ lock = this.acquireLock(
);
```
-Тогда текущий владелец ресурса (или диспетчер блокировок) может, в зависимости от ситуации, отдавать владение ресурсом или, наоборот, запрещать перехват. Скажем, если открытие панели инициировано программистом через вызов API компонента (а не пользователем через выбор предложения в списке), оно может иметь более высокий приоритет и быть разрешено:
+Тогда текущий владелец ресурса (или диспетчер блокировок, если мы реализуем такой объект) может, в зависимости от ситуации, отдавать владение ресурсом или, наоборот, запрещать перехват. Скажем, если открытие панели инициировано программистом через вызов API компонента (а не пользователем через выбор предложения в списке), оно может иметь более высокий приоритет и быть разрешено:
```typescript
lock.events.on('tryAcquire', (actor) => {
@@ -154,7 +156,7 @@ lock.events.on('tryAcquire', (actor) => {
```typescript
lock.events.on('lost', () => {
- this.cancelFullDataLoad();
+ this.cancelFullOfferDataLoad();
})
```
@@ -164,6 +166,7 @@ lock.events.on('lost', () => {
* открыть панель предложения;
* вместо настоящих данных отобразить спиннер или какую-то другую индикацию загрузки;
* асинхронно обновить отображение при получении ответа от сервера.
+
Однако в постановке проблемы это ничего не меняет: нам всё ещё нужно разработать политику разрешения конфликтов для случая, если какой-то актор пытается открыть панель предложения, пока загрузка данных ещё не закончена, для чего нам вновь нужны разделяемые ресурсы и их захват.
Отметим, что в современном фронтенде (к нашему большому сожалению) подобные упражнения с захватом контроля на время загрузки данных или анимации компонентов практически не производятся (считается, что такие асинхронные операции происходят быстро, и коллизии доступа не представляют собой проблемы). Однако, если асинхронные операции выполняются долго (происходят длительные или многоступенчатые загрузки данных, сложные анимации), пренебрежение организацией доступа может быть очень серьёзной UX-проблемой.
\ No newline at end of file
