docs: add student occurrence index finder task

2026-08-28 23:11:28 +04:00
parent 81afad5ecd
commit b6354bf133
1 changed files with 688 additions and 0 deletions
@@ -0,0 +1,688 @@
+# Техническое задание: многопоточный поиск индексов `Student`
+
+## Задача
+
+Реализовать многопоточный поиск всех вхождений заданного объекта `Student` в `MyList<Student>`.
+
+Метод **не должен выводить никаких сообщений в консоль**.
+
+Результатом работы должен быть массив `int[]`, содержащий индексы всех элементов исходной коллекции, которые равны переданному `Student`.
+
+Сравнение выполнять через существующий `Student.equals()`.
+
+---
+
+## Входная информация
+
+Основной метод принимает:
+
+```java
+MyList<Student> students
+```
+
+Исходная коллекция студентов.
+
+```java
+Student target
+```
+
+Студент, вхождения которого необходимо найти.
+
+---
+
+## Выходная информация
+
+Метод возвращает:
+
+```java
+int[]
+```
+
+Массив должен содержать индексы всех совпавших элементов.
+
+Пример:
+
+```text
+Исходная коллекция:
+
+[Student A, Student B, Student A, Student C, Student A]
+
+Результат:
+
+[0, 2, 4]
+```
+
+Индексы должны быть расположены в порядке возрастания.
+
+При отсутствии совпадений:
+
+```text
+[]
+```
+
+При пустой коллекции:
+
+```text
+[]
+```
+
+---
+
+# Название класса
+
+```text
+StudentOccurrenceIndexFinder
+```
+
+---
+
+# Публичные методы и контракты
+
+## `findOccurrences`
+
+```java
+public int[] findOccurrences(
+        MyList<Student> students,
+        Student target
+);
+```
+
+Метод должен:
+
+1. Проверить входные параметры.
+2. Разделить коллекцию на диапазоны индексов.
+3. Передать каждый диапазон отдельной задаче.
+4. Выполнить поиск в нескольких потоках.
+5. Получить от каждого потока найденные индексы.
+6. Объединить результаты.
+7. Вернуть индексы в порядке возрастания.
+8. Не изменять исходную коллекцию.
+9. Не изменять объекты `Student`.
+10. Не выводить ничего в консоль.
+
+---
+
+# Вспомогательные методы
+
+Количество и вид `private` методов могут быть выбраны разработчиком.
+
+Рекомендуется выделить:
+
+```java
+private int calculateThreadCount(int size);
+```
+
+Определяет количество рабочих потоков.
+
+```java
+private int countChunkSize(int size, int threadCount);
+```
+
+Определяет размер диапазона для одной задачи.
+
+```java
+private MyList<Integer> findInRange(
+        MyList<Student> students,
+        Student target,
+        int fromIndex,
+        int toIndex
+);
+```
+
+Обрабатывает диапазон:
+
+```text
+[fromIndex, toIndex)
+```
+
+и возвращает индексы найденных совпадений.
+
+---
+
+# Работа с многопоточностью
+
+## Рекомендуемый подход
+
+Не использовать общий контейнер результатов, к которому одновременно обращаются несколько потоков.
+
+Также **не рекомендуется использовать мьютексы** (`synchronized`, `Lock`, `ReentrantLock`) для хранения результата.
+
+Лучше использовать модель:
+
+```text
+                MyList<Student>
+                       │
+          ┌────────────┼────────────┐
+          ↓            ↓            ↓
+      Поток 1       Поток 2       Поток 3
+       диапазон     диапазон       диапазон
+          │            │            │
+          ↓            ↓            ↓
+      MyList<Integer> MyList<Integer> MyList<Integer>
+          └────────────┼────────────┘
+                       ↓
+                 основной поток
+                       ↓
+                    merge
+                       ↓
+                     int[]
+```
+
+Каждый поток создаёт **собственный контейнер `MyList<Integer>`** и записывает найденные индексы только в него.
+
+Это позволяет избежать состояния гонки без синхронизации общей структуры.
+
+---
+
+# Разбиение коллекции на потоки
+
+Количество потоков рекомендуется определять на основании:
+
+```java
+Runtime.getRuntime().availableProcessors()
+```
+
+Количество потоков не должно превышать количество элементов:
+
+```text
+threadCount = min(
+    availableProcessors(),
+    students.size()
+)
+```
+
+### Пример
+
+Для коллекции из `10000` элементов и четырёх рабочих потоков:
+
+```text
+Поток 1 → [0, 2500)
+Поток 2 → [2500, 5000)
+Поток 3 → [5000, 7500)
+Поток 4 → [7500, 10000)
+```
+
+Каждый индекс должен принадлежать **ровно одному диапазону**.
+
+Не допускаются:
+
+- пропущенные индексы;
+- обработка одного индекса несколькими потоками.
+
+---
+
+# Поиск внутри потока
+
+Каждая задача обрабатывает только свой диапазон.
+
+Для каждого индекса:
+
+```java
+Student student = students.get(index);
+```
+
+затем:
+
+```java
+target.equals(student)
+```
+
+Если результат `true`, индекс добавляется в локальный:
+
+```java
+MyList<Integer>
+```
+
+Пример:
+
+```text
+Поток 1 → [0, 8, 15]
+Поток 2 → [21, 24]
+Поток 3 → [30, 42, 48]
+Поток 4 → [63]
+```
+
+---
+
+# Объединение результатов
+
+Основной поток после завершения всех задач должен получить локальные результаты и объединить их.
+
+Рекомендуется передавать задачи в порядке возрастания диапазонов:
+
+```text
+Результат 1 → диапазон 0
+Результат 2 → диапазон 1
+Результат 3 → диапазон 2
+...
+```
+
+Если каждая задача добавляет индексы в возрастающем порядке, а результаты объединяются в порядке диапазонов, итоговый массив уже будет отсортирован:
+
+```text
+[0, 8, 15, 21, 24, 30, 42, 48, 63]
+```
+
+В этом случае дополнительная сортировка результата не требуется.
+
+**`Arrays.sort()` и другие готовые методы сортировки использовать не следует**, поскольку порядок можно гарантировать самим алгоритмом объединения.
+
+---
+
+# Потокобезопасность
+
+## Мьютексы
+
+Использование мьютексов для результата **не требуется**.
+
+Не рекомендуется использовать:
+
+```java
+synchronized
+```
+
+```java
+Lock
+```
+
+```java
+ReentrantLock
+```
+
+```java
+AtomicInteger
+```
+
+для общего результата.
+
+Причина: потоки не должны изменять одну общую структуру.
+
+Каждый поток работает со своим:
+
+```text
+MyList<Integer>
+```
+
+а объединение выполняется после завершения параллельной части одним потоком.
+
+---
+
+# Рекомендуемые классы и импорты
+
+Для реализации рекомендуется использовать стандартные средства Java:
+
+```java
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+```
+
+Рекомендуемая схема:
+
+```text
+ExecutorService
+      ↓
+Callable<MyList<Integer>>
+      ↓
+Future<MyList<Integer>>
+```
+
+Каждый `Callable` обрабатывает свой диапазон и возвращает собственный `MyList<Integer>`.
+
+После получения всех `Future` основной метод объединяет результаты.
+
+После завершения работы `ExecutorService` должен быть корректно закрыт.
+
+При `InterruptedException` необходимо восстановить статус прерывания текущего потока:
+
+```java
+Thread.currentThread().interrupt();
+```
+
+---
+
+# Использование `MyList`
+
+Сторонние контейнеры **не допускаются**.
+
+Запрещено использовать:
+
+```text
+ArrayList
+LinkedList
+Vector
+CopyOnWriteArrayList
+ConcurrentLinkedQueue
+и другие стандартные контейнеры
+```
+
+как хранилище промежуточных или итоговых результатов.
+
+Для результатов каждого потока использовать:
+
+```java
+MyList<Integer>
+```
+
+Итог преобразовать в:
+
+```java
+int[]
+```
+
+---
+
+# Требуется ли изменять `MyList`
+
+Текущего интерфейса **достаточно для реализации задачи**:
+
+```java
+public interface MyList<T> {
+
+  void add(T element);
+
+  T get(int index);
+
+  T set(int index, T element);
+
+  T remove(int index);
+
+  int size();
+
+  boolean isEmpty();
+}
+```
+
+Дополнительные методы добавлять **не требуется**.
+
+Для задачи достаточно:
+
+```java
+size()
+get(index)
+add(index)
+```
+
+Поскольку поиск выполняется только на чтение, а результаты каждого потока добавляются в его собственный `MyList<Integer>`, существующего интерфейса достаточно.
+
+### Важно
+
+Метод:
+
+```java
+void add(T element);
+```
+
+должен добавлять элемент в конец коллекции.
+
+Это позволяет каждому потоку формировать свои индексы в порядке их обнаружения.
+
+---
+
+# Использование `Student`
+
+Изменения в `Student` **не требуются**.
+
+Использовать существующий метод:
+
+```java
+equals(Object obj)
+```
+
+Сравнение выполнять:
+
+```java
+target.equals(students.get(index))
+```
+
+Не использовать:
+
+```text
+==
+```
+
+Не сравнивать объекты вручную по отдельным полям.
+
+Не использовать `toString()` для определения совпадения.
+
+---
+
+# `StudentBuilder`
+
+Изменения в `StudentBuilder` **не требуются**.
+
+Он не участвует в алгоритме поиска.
+
+---
+
+# Обработка входных данных
+
+Если:
+
+```java
+students == null
+```
+
+выбросить:
+
+```java
+IllegalArgumentException
+```
+
+Если:
+
+```java
+target == null
+```
+
+выбросить:
+
+```java
+IllegalArgumentException
+```
+
+Для пустой коллекции вернуть:
+
+```java
+new int[0]
+```
+
+Без создания рабочих потоков.
+
+---
+
+# Обобщённый алгоритм реализации
+
+```text
+1. Проверить students и target.
+2. Получить размер коллекции.
+3. Если размер равен 0 → вернуть [].
+4. Вычислить количество потоков.
+5. Разделить индексы коллекции на непересекающиеся диапазоны.
+6. Создать Callable для каждого диапазона.
+7. Запустить задачи через ExecutorService.
+8. Каждый поток:
+      - получает fromIndex и toIndex;
+      - проходит свой диапазон;
+      - сравнивает Student через equals();
+      - записывает найденные индексы в собственный MyList<Integer>.
+9. Основной поток получает результаты через Future.
+10. Объединяет MyList<Integer> в порядке диапазонов.
+11. Преобразует результат в int[].
+12. Возвращает массив.
+```
+
+---
+
+# Примеры тестов
+
+## Одно совпадение
+
+```text
+[A, B, C, D]
+```
+
+Искомый:
+
+```text
+C
+```
+
+Ожидается:
+
+```text
+[2]
+```
+
+## Несколько совпадений
+
+```text
+[A, B, A, C, A]
+```
+
+Ожидается:
+
+```text
+[0, 2, 4]
+```
+
+## Нет совпадений
+
+```text
+[A, B, C]
+```
+
+Искомый:
+
+```text
+D
+```
+
+Ожидается:
+
+```text
+[]
+```
+
+## Все элементы совпадают
+
+```text
+[A, A, A, A]
+```
+
+Ожидается:
+
+```text
+[0, 1, 2, 3]
+```
+
+## Пустая коллекция
+
+Ожидается:
+
+```text
+[]
+```
+
+## Один элемент
+
+Проверить:
+
+```text
+[A] + A → [0]
+[A] + B → []
+```
+
+## Проверка границ диапазонов потоков
+
+Проверить коллекции размеров:
+
+```text
+1
+2
+3
+4
+10
+100
+1000
+```
+
+Особое внимание уделить совпадениям:
+
+```text
+на последнем элементе одного диапазона;
+на первом элементе следующего диапазона.
+```
+
+Каждый индекс должен быть найден ровно один раз.
+
+## Проверка порядка результата
+
+Создать совпадения в разных диапазонах.
+
+Проверить, что результат имеет вид:
+
+```text
+[0, 3, 7, 12, 25, 49, 100]
+```
+
+и находится в порядке возрастания без использования дополнительной сортировки.
+
+## Проверка `Student.equals()`
+
+Создать два разных экземпляра `Student` с одинаковыми значениями полей.
+
+Один поместить в коллекцию, второй передать как `target`.
+
+Проверить, что индекс считается совпадением согласно `equals()`.
+
+## Проверка неизменности коллекции
+
+После выполнения метода проверить:
+
+- размер `MyList`;
+- порядок элементов;
+- значения всех элементов.
+
+## Проверка отсутствия вывода
+
+Перехватить стандартный вывод и убедиться, что выполнение `findOccurrences()` не выводит сообщений в консоль.
+
+## Большая коллекция
+
+Создать коллекцию, например из `100000` студентов, с заранее известными индексами совпадений.
+
+Проверить:
+
+- все ожидаемые индексы найдены;
+- лишних индексов нет;
+- индексы идут по возрастанию;
+- итоговый массив имеет правильный размер.
+
+## Git
+
+Название ветки:
+
+```text
+feature/student-occurrence-index-finder
+```
+
+## Результат
+
+Необходимо реализовать:
+
+```text
+StudentOccurrenceIndexFinder.java
+```
+
+Существующие интерфейсы и классы:
+
+```text
+MyList.java
+Student.java
+StudentBuilder.java
+```
+
+изменять не требуется.