feat(concurrency): 🎸 fork-join, translated

Refers: #8

Author: rcmoutinho

book/06-concurrency/sections/04-fork-join.asc

@@ -1,38 +1,36 @@
 :java-package: src/org/j6toj8/concurrency
 :section-java-package: ../../../{java-package}
 
-=== Framework Fork/Join
+=== Fork/Join Framework
 
-.Objetivo
+.Objective
 --------------------------------------------------
 Use the parallel Fork/Join Framework
--
-Usar o Framework Fork/Join de paralelismo
 --------------------------------------------------
 
-Com o framework de Fork/Join é possível dividir uma tarefa grande em pedaços menores e executá-los em paralelo. A utilização do framework é simples. A criação de tarefas quebradas em várias partes pode ser um pouco mais complexa. 
+With the Fork/Join framework you can split a large task into smaller pieces and execute them in parallel. The use of the framework is simple. Creating broken tasks into several parts can be a bit more complex.
 
-Uma tarefa geralmente segue um comportamento padrão:
+A task usually follows a default behavior:
 
-* Recebe um valor;
-* Avalia se o valor é pequeno o suficiente para executar a tarefa com ele;
-** Caso positivo, executa a tarefa com aquele valor;
-** Caso negativo, quebra em uma ou mais partes e cria novas tarefas menores;
-* Segue executando de forma recursiva.
+* Receives a value;
+* Evaluates if the value is small enough to perform the task with it;
+** If so, execute the task with that value;
+** If not, it breaks into one or more parts and creates new smaller tasks;
+* Continues running recursively.
 
-Serão apresentados exemplos utilizando a classe `RecursiveAction`, que não retorna valores, e por isso sua implementação é mais simples. E utilizando a classe `RecursiveTask`, que retorna valores e por isso sua implementação é um pouco mais complexa.
+Examples will be presented using the `RecursiveAction` class, which returns no values, so its implementation is simpler. And using the `RecursiveTask` class, which returns values ​​and so its implementation is a bit more complex.
 
-Os exemplos são grandes, pois é necessário implementar toda a classe `RecursiveAction` ou `RecursiveTask` para o exemplo funcionar. Por isso, os passos serão descritos com comentários no código, explicando o funcionamento de cada chamada realizada ao framework.
+The examples are large because you need to implement the entire `RecursiveAction` or `RecursiveTask` class for the example to work. Therefore, the steps will be described with comments in the code, explaining the operation of each call made to the framework.
 
-. É possível implementar uma `RecursiveAction` que divide uma tarefa grande em partes menores.
+. You can implement a `RecursiveAction` that divides a large task into smaller parts.
 +
 [source,java,indent=0]
 .{java-package}/forkjoin/ForkJoin_RecursiveAction.java
 ----
 include::{section-java-package}/forkjoin/ForkJoin_RecursiveAction.java[tag=code]
 ----
 +
-.Saída no console
+.console output
 [source,console]
 ----
 ForkJoinPool-1-worker-1 - ABCDEF
@@ -41,23 +39,23 @@ ForkJoinPool-1-worker-2 - NOPQRS
 ForkJoinPool-1-worker-3 - GHIJKLM
 ----
 +
-.. Esse exemplo cria uma tarefa do tipo `RecursiveAction` chamada `ImpressaoDeStrings`.
-.. Essa `RecursiveAction` recebe uma `String` para imprimir no Console.
-.. No método `compute`, a tarefa decide se irá imprimir diretamente no console, ou se irá dividir esse trabalho em duas partes: caso a `String` tenha menos que 10 caracteres, ela imprime diretamente no Console; caso contrário, divide o trabalho em duas novas tarefas.
+.. This example creates a task of type `RecursiveAction` called `StringPrinting`.
+.. This `RecursiveAction` gets a `String` to print to the Console.
+.. In the `compute` method, the job decides whether to print directly to the console, or to split this job into two parts: if the `String` is less than 10 characters long, it prints directly to the console; otherwise it splits the work into two new tasks.
 +
-Perceba que cada impressão no console é realizada em uma _thread_ diferente, ficando claro que o trabalho está sendo compartilhado por múltiplas _threads_.
+Note that each print on the console is performed on a different _thread_, making it clear that the job is being shared by multiple _threads_.
 +
-Perceba também que o processamento da String não retorna nenhum valor, e por isso foi utilizada a classe `RecursiveAction`.
+Also note that String processing returns no value, so the `RecursiveAction` class was used.
 
-. Caso seja necessário retornar um valor, é possível implementar uma `RecursiveTask` que divide uma tarefa grande em partes menores.
+. If you need to return a value, you can implement a `RecursiveTask` that divides a large task into smaller parts.
 +
 [source,java,indent=0]
 .{java-package}/forkjoin/ForkJoin_RecursiveTask.java
 ----
 include::{section-java-package}/forkjoin/ForkJoin_RecursiveTask.java[tag=code]
 ----
 +
-.Saída no console
+.console output
 [source,console]
 ----
 ForkJoinPool-1-worker-3 - NOPQRS
@@ -67,21 +65,21 @@ ForkJoinPool-1-worker-1 - TUVWXYZ
 Resultado da execução: 26
 ----
 +
-.. Esse exemplo cria uma tarefa do tipo `RecursiveTask` chamada `ImpressaoDeStrings`.
-.. Essa `RecursiveTask` recebe uma `String` para imprimir no Console.
-.. No método `compute`, a tarefa decide se irá imprimir diretamente no console, ou se irá dividir esse trabalho em duas partes: caso a `String` tenha menos que 10 caracteres, ela imprime diretamente no Console; caso contrário, divide o trabalho em duas novas tarefas.
+.. This example creates a task of type `RecursiveTask` called `StringPrinting`.
+.. This `RecursiveTask` is given a `String` to print to the Console.
+.. In the `compute` method, the job decides whether to print directly to the console, or to split this job into two parts: if the `String` is less than 10 characters long, it prints directly to the console; otherwise it splits the work into two new tasks.
 +
-Perceba também que o processamento da String retorna quantos caracteres foram impressos, e por isso foi utilizada a classe `RecursiveTask`.
-
+Also note that String processing returns how many characters were printed, so the `RecursiveTask` class was used.
 
+.References
 ****
 
 * Managing Concurrent Processes
 +
-Boyarsky, Jeanne; Selikoff, Scott. OCP: Oracle Certified Professional Java SE 8 Programmer II Study Guide (p. 377). Wiley. Edição do Kindle. 
+Boyarsky, Jeanne; Selikoff, Scott. OCP: Oracle Certified Professional Java SE 8 Programmer II Study Guide (p. 377). Wiley. Kindle Edition.
 
 * https://www.baeldung.com/java-fork-join[Guide to the Fork/Join Framework in Java.]
 
 * https://docs.oracle.com/javase/tutorial/essential/concurrency/forkjoin.html[Fork/Join.] The Java™ Tutorials.
 
-****
+****

src/org/j6toj8/concurrency/forkjoin/ForkJoin_RecursiveAction.java

@@ -9,58 +9,57 @@
 public class ForkJoin_RecursiveAction {
 
   // tag::code[]
-  // Classe que representa a tarefa que será executada
-  static class ImpressaoDeStrings extends RecursiveAction {
+  // Class that represents the task that will be performed
+  static class StringPrinterAction extends RecursiveAction {
 
-    private String stringParaImprimir; // String que será impressa
+    private String stringToPrint;
 
-    public ImpressaoDeStrings(String stringParaImprimir) {
-      this.stringParaImprimir = stringParaImprimir;
+    public StringPrinterAction(String stringToPrint) {
+      this.stringToPrint = stringToPrint;
     }
 
     @Override
     protected void compute() {
-      if (stringParaImprimir.length() < 10) {
-        // se a String tiver menos de 10 caracteres, será impressa
-        System.out.println(Thread.currentThread().getName() + " - " + stringParaImprimir);
+      if (stringToPrint.length() < 10) {
+        // if String is less than 10 characters, will print
+        System.out.println(Thread.currentThread().getName() + " - " + stringToPrint);
       } else {
-        // caso contrário, são criadas duas novas tarefas, uma com a primeira metade da String
-        // e outra com a segunda metade da String
-        List<ImpressaoDeStrings> novasTarefas = divideEmDuasTarefas();
-        
-        // Invoca a execução das duas tarefas criadas
-        ForkJoinTask.invokeAll(novasTarefas);
+        // otherwise, two new tasks are created, one with the first half of String and one with the second half of String
+        List<StringPrinterAction> newTasks = divideInTwoTasks();
+
+        // Invoke execution of two created tasks
+        ForkJoinTask.invokeAll(newTasks);
       }
     }
 
-    private List<ImpressaoDeStrings> divideEmDuasTarefas() {
-      // esse método divide a String em duas partes e cria duas novas tarefas
-      // cada uma das tarefas recebe uma parte da String
+    private List<StringPrinterAction> divideInTwoTasks() {
+      // this method splits the string into two parts and creates two new tasks
+      // each task gets a part of the String
 
-      int tamanhoDaString = stringParaImprimir.length();
-      int meioDaString = tamanhoDaString / 2;
+      int stringSize = stringToPrint.length();
+      int stringMiddle = stringSize / 2;
 
-      String primeiraMetade = stringParaImprimir.substring(0, meioDaString);
-      String segundaMetade = stringParaImprimir.substring(meioDaString);
+      String firstHalf = stringToPrint.substring(0, stringMiddle);
+      String secondHalf = stringToPrint.substring(stringMiddle);
 
-      List<ImpressaoDeStrings> acoes = new ArrayList<ImpressaoDeStrings>();
-      acoes.add(new ImpressaoDeStrings(primeiraMetade));
-      acoes.add(new ImpressaoDeStrings(segundaMetade));
-      return acoes;
+      List<StringPrinterAction> actions = new ArrayList<StringPrinterAction>();
+      actions.add(new StringPrinterAction(firstHalf));
+      actions.add(new StringPrinterAction(secondHalf));
+      return actions;
     }
 
   }
 
   public static void main(String[] args) {
-    // string que queremos imprimir
-    String stringParaImprimir = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
-    
-    // tarefa principal que será executada
-    ImpressaoDeStrings tarefa = new ImpressaoDeStrings(stringParaImprimir);
-    
-    // criação do ForkJoinPool e execução da tarefa
+    // string we want to print
+    String stringToPrint= "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+    // main task to be performed
+    StringPrinterAction task = new StringPrinterAction(stringToPrint);
+
+    // ForkJoinPool creation and task execution
     ForkJoinPool forkJoinPool = new ForkJoinPool();
-    forkJoinPool.invoke(tarefa);
+    forkJoinPool.invoke(task);
   }
   // end::code[]
 

src/org/j6toj8/concurrency/forkjoin/ForkJoin_RecursiveTask.java

@@ -4,79 +4,78 @@
 import java.util.List;
 import java.util.concurrent.ForkJoinPool;
 import java.util.concurrent.ForkJoinTask;
-import java.util.concurrent.RecursiveAction;
 import java.util.concurrent.RecursiveTask;
 
 public class ForkJoin_RecursiveTask {
 
   // tag::code[]
-  // Classe que representa a tarefa que será executada
-  static class ImpressaoDeStrings extends RecursiveTask<Integer> {
+  // Class that represents the task that will be performed
+  static class StringPrinter extends RecursiveTask<Integer> {
 
-    private String stringParaImprimir; // String que será impressa
+    private String stringToPrint;
 
-    public ImpressaoDeStrings(String stringParaImprimir) {
-      this.stringParaImprimir = stringParaImprimir;
+    public StringPrinter(String stringToPrint) {
+      this.stringToPrint = stringToPrint;
     }
 
     @Override
     protected Integer compute() {
-      if (stringParaImprimir.length() < 10) {
-        // se a String tiver menos de 10 caracteres, será impressa
-        System.out.println(Thread.currentThread().getName() + " - " + stringParaImprimir);
-        
-        // retornamos a quantidade de caracteres impressos
-        return stringParaImprimir.length();
+      if (stringToPrint.length() < 10) {
+        // if String is less than 10 characters, will print
+        System.out.println(Thread.currentThread().getName() + " - " + stringToPrint);
+
+        // return the amount of characters printed
+        return stringToPrint.length();
       } else {
-        // caso contrário, são criadas duas novas tarefas, uma com a primeira metade da String
-        // e outra com a segunda metade da String
-        List<ImpressaoDeStrings> novasTarefas = divideEmDuasTarefas();
-        ImpressaoDeStrings tarefa1 = novasTarefas.get(0);
-        ImpressaoDeStrings tarefa2 = novasTarefas.get(1);
-        
-        // 'fork' irá enviar a tarefa1 para ser executada em uma nova thread
-        ForkJoinTask<Integer> primeiraTarefa = tarefa1.fork();
-        
-        // 'compute' irá executar a tarefa2 nessa mesma thread
-        Integer resultadoDaTarefa2 = tarefa2.compute();
-
-        // 'join' irá pegar o resultado da tafera1 que estava sendo executada em outra thread
-        Integer resultadoDaTarefa1 = primeiraTarefa.join();
-        
-        // retornamos a soma dos resultados, pois é a quantidade de carateres impressos
-        return resultadoDaTarefa2 + resultadoDaTarefa1;
+        // otherwise, two new tasks are created, one with the first half of String and one with the second half of String
+        List<StringPrinter> newTasks = divideInTwoTasks();
+        StringPrinter task1 = newTasks.get(0);
+        StringPrinter task2 = newTasks.get(1);
+
+        // 'fork' will send task1 to run on a new thread
+        ForkJoinTask<Integer> firstTask = task1.fork();
+
+        // 'compute' will execute task2 on this same thread
+        Integer taskResult2 = task2.compute();
+
+        // 'join' will get the result of task1 that was running on another thread
+        Integer taskResult1 = firstTask.join();
+
+        // return the sum of the results because it is the number of characters printed
+        return taskResult2 + taskResult1;
       }
     }
 
-    private List<ImpressaoDeStrings> divideEmDuasTarefas() {
-      // esse método divide a String em duas partes e cria duas novas tarefas
-      // cada uma das tarefas recebe uma parte da String
-      
-      int tamanhoDaString = stringParaImprimir.length();
-      int meioDaString = tamanhoDaString / 2;
-      
-      String primeiraMetade = stringParaImprimir.substring(0, meioDaString);
-      String segundaMetade = stringParaImprimir.substring(meioDaString);
-      
-      List<ImpressaoDeStrings> acoes = new ArrayList<ImpressaoDeStrings>();
-      acoes.add(new ImpressaoDeStrings(primeiraMetade));
-      acoes.add(new ImpressaoDeStrings(segundaMetade));
-      return acoes;
+    private List<StringPrinter> divideInTwoTasks() {
+      // this method splits the string into two parts and creates two new tasks
+      // each task gets a part of the String
+
+      int stringSize = stringToPrint.length();
+      int stringMiddle = stringSize / 2;
+
+      String firstHalf = stringToPrint.substring(0, stringMiddle);
+      String secondHalf = stringToPrint.substring(stringMiddle);
+
+      List<StringPrinter> actions = new ArrayList<StringPrinter>();
+      actions.add(new StringPrinter(firstHalf));
+      actions.add(new StringPrinter(secondHalf));
+      return actions;
     }
 
   }
 
   public static void main(String[] args) {
-    // string que queremos imprimir
-    String stringParaImprimir = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
-    
-    // tarefa principal que será executada
-    ImpressaoDeStrings tarefa = new ImpressaoDeStrings(stringParaImprimir);
-    
-    // criação do ForkJoinPool e execução da tarefa
+    // string we want to print
+    String stringToPrint= "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+    // main task to be performed
+    StringPrinter task = new StringPrinter(stringToPrint);
+
+    // ForkJoinPool creation and task execution
     ForkJoinPool forkJoinPool = new ForkJoinPool();
-    Integer resultado = forkJoinPool.invoke(tarefa);
-    System.out.println("Resultado da execução: " + resultado);
+    Integer result = forkJoinPool.invoke(task);
+    System.out.println("Execution result: " + result);
+
   }
   // end::code[]