RU: blocking vs non-blocking guide

locale/ru/docs/guides/blocking-vs-non-blocking.md

@@ -1,51 +1,53 @@
 ---
-title: Overview of Blocking vs Non-Blocking
+title: Блокирующие и Неблокирующие Вызовы
 layout: docs.hbs
 ---
 
-# Overview of Blocking vs Non-Blocking
+# Обзор Блокирующих и Неблокирующих Вызовов
 
-This overview covers the difference between **blocking** and **non-blocking**
-calls in Node.js. This overview will refer to the event loop and libuv but no
-prior knowledge of those topics is required. Readers are assumed to have a
-basic understanding of the JavaScript language and Node.js callback pattern.
+Этот обзор рассматривает разницу между **блокирующими** и **неблокирующими**
+вызовами в Node.js. Он ссылается на цикл событий (event loop) и библиотеку libuv,
+однако предварительное знание этих тем не требуется. Предпологается, что
+читатели имеют базовое понимание JavaScript и паттерна обратных вызовов (callback)
+в Node.js.
 
-> "I/O" refers primarily to interaction with the system's disk and
-> network supported by [libuv](http://libuv.org/).
+> Обозначение "I/O" (Ввод/Вывод) в первую очередь ссылается на взаимодействие
+> с системным диском и сетью при поддержке [libuv](http://libuv.org/).
 
 
-## Blocking
+## Блокирование
 
-**Blocking** is when the execution of additional JavaScript in the Node.js
-process must wait until a non-JavaScript operation completes. This happens
-because the event loop is unable to continue running JavaScript while a
-**blocking** operation is occurring.
+О **блокировании** говорят, когда выполнение JS кода в Node.js
+приостановленно до тех пор, пока не завершится работа сторонней операции (например, чтение
+какого-нибудь файла). Так происходит, потому что цикл событий не может продолжить исполнение JavaScript,
+так как работает **блокирующая** операция.
 
-In Node.js, JavaScript that exhibits poor performance due to being CPU intensive
-rather than waiting on a non-JavaScript operation, such as I/O, isn't typically
-referred to as **blocking**. Synchronous methods in the Node.js standard library
-that use libuv are the most commonly used **blocking** operations. Native
-modules may also have **blocking** methods.
+В Node.js медленно исполняемый JS код не принято называть **блокирующим**,
+если причиной тому высокая нагрузка кода на процессор, а не ожидание завершения
+сторонней операции. Синхронные методы в стандартной библиотеке Node.js,
+которые используют libuv, наиболее часто применяемые **блокирующие** операции.
+Нативные модули также могут иметь **блокирующие** методы.
 
-All of the I/O methods in the Node.js standard library provide asynchronous
-versions, which are **non-blocking**, and accept callback functions. Some
-methods also have **blocking** counterparts, which have names that end with
-`Sync`.
+Все I/O методы в стандартной библиотеке Node.js предоставляют свои асинхронные версии,
+которые являются **неблокирующими** и принимают функции обратного вызова
+в качестве аргумента. Некоторые методы также имеют свои **блокирующие** аналоги.
+Названия таких методов закнчиваются на `Sync`.
 
 
-## Comparing Code
+## Сравнение Кода
 
-**Blocking** methods execute **synchronously** and **non-blocking** methods
-execute **asynchronously**.
+**Блокирующие** методы исполняются **синхронно**, а **неблокирующие** методы
+исполняются **асинхронно**.
 
-Using the File System module as an example, this is a **synchronous** file read:
+Возьмем модуль File System для примера. Вот пример **синхронного** чтения файла:
 
 ```js
 const fs = require('fs');
-const data = fs.readFileSync('/file.md'); // blocks here until file is read
+// исполнение кода заблокированно, пока файл не будет полностью считан
+const data = fs.readFileSync('/file.md');
 ```
 
-And here is an equivalent **asynchronous** example:
+А вот эквивалентный **асинхронный** пример:
 
 ```js
 const fs = require('fs');
@@ -54,63 +56,62 @@ fs.readFile('/file.md', (err, data) => {
 });
 ```
 
-The first example appears simpler than the second but has the disadvantage of
-the second line **blocking** the execution of any additional JavaScript until
-the entire file is read. Note that in the synchronous version if an error is
-thrown it will need to be caught or the process will crash. In the asynchronous
-version, it is up to the author to decide whether an error should throw as
-shown.
+Первый пример выглядит проще чем второй, но он имеет один недостаток: вторая строка
+**блокирует** исполнение любого нижеследующего кода, до тех пор, пока
+весь file.md не будет считан. Обратите внимание, если синхронная версия кода сгенерирует
+исключение, его нужно обработать, иначе процесс Node.js "упадёт". В асинхронном варианте
+выбор сгенерировать исключение или нет оставлено на усмотрение программиста.
 
-Let's expand our example a little bit:
+Давайте немного расширим наш пример:
 
 ```js
 const fs = require('fs');
-const data = fs.readFileSync('/file.md'); // blocks here until file is read
+// исполнение кода заблокированно, пока файл не будет полностью считан
+const data = fs.readFileSync('/file.md');
 console.log(data);
-moreWork(); // will run after console.log
+moreWork(); // функция будет исполнена, после console.log
 ```
 
-And here is a similar, but not equivalent asynchronous example:
+А вот похожий, но не эквивалентный асинхронный пример:
 
 ```js
 const fs = require('fs');
 fs.readFile('/file.md', (err, data) => {
   if (err) throw err;
   console.log(data);
 });
-moreWork(); // will run before console.log
+moreWork(); // функция будет исполнена до console.log
 ```
 
-In the first example above, `console.log` will be called before `moreWork()`. In
-the second example `fs.readFile()` is **non-blocking** so JavaScript execution
-can continue and `moreWork()` will be called first. The ability to run
-`moreWork()` without waiting for the file read to complete is a key design
-choice that allows for higher throughput.
+В первом примере метод `console.log` будет вызван до срабатывания функции `moreWork()`.
+Во втором примере метод `fs.readFile()` является **неблокирующим**, поэтому исполнение
+JavaScript может продолжаться, не дожидаясь окончания его работы. Как следствие
+функция `moreWork()` сработает раньше `console.log`. Эта возможность — отсутствие необходимости
+дожидаться окончания чтения файла и других системных вызовов — ключевое
+инженерное решение, которое обеспечивает высокую пропускную способность Node.js.
 
 
-## Concurrency and Throughput
+## Конкурентность и Пропускная Способность
 
-JavaScript execution in Node.js is single threaded, so concurrency refers to the
-event loop's capacity to execute JavaScript callback functions after completing
-other work. Any code that is expected to run in a concurrent manner must allow
-the event loop to continue running as non-JavaScript operations, like I/O, are
-occurring.
+Исполнение JavaScript в Node.js является однопоточным. Поэтому, говоря о конкурентности
+(параллельности вычислений) в Node.js, подразумевают, что после того, как цикл событий обработал синхронный код,
+он способен обработать функции обратного вызова. Подобно сторонним операциям (таким как I/O),
+любой конкурентный код должен позволять циклу событий продолжать свою работу.
 
-As an example, let's consider a case where each request to a web server takes
-50ms to complete and 45ms of that 50ms is database I/O that can be done
-asynchronously. Choosing **non-blocking** asynchronous operations frees up that
-45ms per request to handle other requests. This is a significant difference in
-capacity just by choosing to use **non-blocking** methods instead of
-**blocking** methods.
+В качестве примера возьмем запросы к веб-серверу. Допустим, обработка сервером одного запроса
+занимает 50мс. Из этих 50мс, 45мс уходит на операции чтения/записи в базу данных.
+С базой данных можно взаимодействовать и **асинхронно**. При таком подходе, на каждый запрос
+к веб-серверу **неблокирующая** асинхронная операция высвободит 45мс для обработки других
+запросов, а это существенная разница.
 
-The event loop is different than models in many other languages where additional
-threads may be created to handle concurrent work.
+Обработка конкурентной (параллельной) работы при помощи цикла событий в Node.js
+отличается от подходов во многих других языках программрования, в которых могут
+создаваться дополнительные потоки.
 
 
-## Dangers of Mixing Blocking and Non-Blocking Code
+## Опасность смешивания Блокирующего и Неблокирующего Кода
 
-There are some patterns that should be avoided when dealing with I/O. Let's look
-at an example:
+Существуют паттерны, которые следует избегать при работе с I/O. Взглянем на пример:
 
 ```js
 const fs = require('fs');
@@ -121,10 +122,9 @@ fs.readFile('/file.md', (err, data) => {
 fs.unlinkSync('/file.md');
 ```
 
-In the above example, `fs.unlinkSync()` is likely to be run before
-`fs.readFile()`, which would delete `file.md` before it is actually read. A
-better way to write this, which is completely **non-blocking** and guaranteed to
-execute in the correct order is:
+В вышеукзанном примере метод `fs.unlinkSync()`, с высокой вероятностью, будет исполнен до
+`fs.readFile()`. Это приведет к удалению файла до его прочтения. Лучше переписать
+этот код в **неблокирующем** виде, что гарантирует правильный порядок исполнения методов:
 
 
 ```js
@@ -138,11 +138,11 @@ fs.readFile('/file.md', (readFileErr, data) => {
 });
 ```
 
-The above places a **non-blocking** call to `fs.unlink()` within the callback of
-`fs.readFile()` which guarantees the correct order of operations.
+В последнем примере  **неблокирующий** вызов метода `fs.unlink()` расположен внутри функции обратного вызова
+`fs.readFile()`. Такой подход гарантирует парвильную последовательность операций.
 
 
-## Additional Resources
+## Дополнительные рессурсы
 
 - [libuv](http://libuv.org/)
-- [About Node.js](https://nodejs.org/en/about/)
+- [О Node.js](https://nodejs.org/en/about/)

locale/ru/docs/guides/index.md

@@ -1,23 +1,23 @@
 ---
-title: Guides
+title: Руководства
 layout: docs.hbs
 ---
 
-# Guides
+# Руководства
 
-## General
+## Общее
 
-- [Getting Started Guide](getting-started-guide/)
+- [Первые шаги](getting-started-guide/)
 - [Debugging - Getting Started](debugging-getting-started/)
 - [Easy profiling for Node.js Applications](simple-profiling/)
 - [Diagnostics - Flame Graphs](diagnostics-flamegraph/)
 - [Dockerizing a Node.js web app](nodejs-docker-webapp/)
 - [Migrating to safe Buffer constructors](buffer-constructor-deprecation/)
 
 
-## Node.js core concepts
+## Ключевые концепции Node.js
 
-- [Overview of Blocking vs Non-Blocking](blocking-vs-non-blocking/)
+- [Блокирующие и Неблокирующие Вызовы](blocking-vs-non-blocking/)
 - [The Node.js Event Loop, Timers, and `process.nextTick()`](event-loop-timers-and-nexttick/)
 - [Don't Block the Event Loop (or the Worker Pool)](dont-block-the-event-loop/)
 - [Timers in Node.js](timers-in-node/)