# Описание компонента zh_vector

## Общие сведения

**zh_vector** — это компонент для ESP-IDF (фреймворк для программирования микроконтроллеров ESP32), реализующий динамический вектор (динамический массив) с автоматическим управлением памятью и потокобезопасностью.

Компонент предоставляет универсальную структуру данных «вектор», которая может хранить элементы любого типа через указатели `void`, автоматически увеличивает и уменьшает свою ёмкость, а также обеспечивает потокобезопасную работу с помощью мьютексов FreeRTOS.

## Основные возможности

1. **Универсальность типов** — поддержка любых типов данных через указатели `void`.
2. **Динамическая ёмкость** — автоматическое увеличение и уменьшение выделенной памяти.
3. **Максимальная ёмкость** — до 65 535 элементов (используется 16-битный индекс `uint16_t`).
4. **Потокобезопасность** — все операции защищены мьютексом FreeRTOS.
5. **Автоматическое управление памятью** — используется ESP-IDF функция `heap_caps` для работы с кучей ESP32.
6. **Гибкая вставка** — поддержка вставки элементов как в начало, так и в конец вектора.
7. **Удаление дубликатов и поиск** — возможность удаления дубликатов и поиска элементов по содержимому или по полю внутри структуры.

## Внутреннее устройство

### Структура `zh_vector_t`

Внутренняя структура вектора содержит следующие поля:

| Поле | Тип | Описание |
|------|-----|----------|
| `items` | `void **` | Массив указателей, каждый из которых указывает на отдельно выделенную память для фактических данных элемента |
| `capacity` | `uint16_t` | Текущая выделенная ёмкость массива `items` (максимум 65 535) |
| `size` | `uint16_t` | Текущее количество элементов в векторе |
| `unit` | `uint16_t` | Размер одного элемента в байтах |
| `mutex` | `SemaphoreHandle_t` | Мьютекс FreeRTOS для потокобезопасности |
| `lock` | `portMUX_TYPE` | Секция критической защиты для флагов удаления и счётчика ссылок |
| `deleting` | `bool` | Флаг, указывающий, что вектор удаляется и новые операции должны быть отклонены |
| `refcount` | `uint16_t` | Счётчик операций, находящихся в процессе выполнения |

### Управление памятью

Каждый элемент вектора хранится как **отдельное выделение памяти**. Это означает, что:
- Массив `items` содержит указатели на элементы.
- Каждый элемент выделяется отдельно через `heap_caps_calloc()`.
- При удалении элемента его память освобождается через `heap_caps_free()`.
- При удалении всего вектора последовательно освобождаются все элементы, затем массив `items` и сама структура `zh_vector_t`.

## API (интерфейс)

### Инициализация и освобождение

| Функция | Описание |
|---------|----------|
| `zh_vector_init()` | Инициализирует новый вектор. Принимает указатель на указатель вектора и размер элемента в байтах. Создаёт структуру, выделяет нулевую ёмкость и создаёт мьютекс. |
| `zh_vector_free()` | Освобождает все ресурсы: элементы, массив, мьютекс и структуру. Устанавливает флаг `deleting` и ожидает завершения всех текущих операций (до тех пор, пока `refcount` не станет нулём). |

### Получение информации

| Функция | Описание |
|---------|----------|
| `zh_vector_get_size()` | Возвращает текущее количество элементов в векторе. |
| `zh_vector_get_capacity()` | Возвращает текущую выделенную ёмкость (максимальное количество элементов, для которого выделена память). |

### Вставка элементов

| Функция | Описание |
|---------|----------|
| `zh_vector_push_front()` | Вставляет копию элемента в начало вектора (индекс 0). Все существующие элементы сдвигаются на одну позицию вправо. Если ёмкость исчерпана, массив увеличивается. |
| `zh_vector_push_back()` | Вставляет копию элемента в конец вектора. Если ёмкость исчерпана, массив увеличивается. |

### Доступ и модификация

| Функция | Описание |
|---------|----------|
| `zh_vector_get_item()` | Копирует элемент по указанному индексу в предоставленный буфер. |
| `zh_vector_change_item()` | Заменяет содержимое элемента по указанному индексу новыми данными. |

### Удаление элементов

| Функция | Описание |
|---------|----------|
| `zh_vector_delete_item()` | Удаляет элемент по указанному индексу. Освобождает память элемента, сдвигает оставшиеся элементы влево. Обновляет `size`. |
| `zh_vector_delete_back()` | Удаляет последний элемент вектора. |
| `zh_vector_delete_front()` | Удаляет первый элемент вектора. Сдвигает оставшиеся элементы влево. |

### Поиск и очистка

| Функция | Описание |
|---------|----------|
| `zh_vector_remove_duplicates()` | Удаляет дубликаты элементов. Сравнивает элементы побайтово через `memcmp`. При обнаружении дубликата он удаляется. |
| `zh_vector_find_item()` | Ищет первый элемент, побайтово совпадающий с заданным. Возвращает индекс или `-1`, если элемент не найден. |
| `zh_vector_find_item_in_field()` | Ищет элемент по значению конкретного поля внутри структуры. Позволяет искать по любому полю структуры, вычисляя смещение поля от начала структуры. |

## Потокобезопасность

Все публичные функции работают с вектором через двухуровневую систему синхронизации:

1. **`_zh_vector_take()` / `_zh_vector_give()`** — механизм счётчика ссылок.
   - Перед началом любой операции вызывается `_zh_vector_take()`, который увеличивает `refcount` и проверяет, что вектор не удаляется (флаг `deleting` равен `false`).
   - После завершения операции вызывается `_zh_vector_give()`, который уменьшает `refcount`.
   - Функция `zh_vector_free()` устанавливает `deleting = true` и ожидает, пока `refcount` не станет нулём. Это гарантирует, что все текущие операции завершатся перед освобождением памяти.

2. **Мьютекс FreeRTOS** — защищает внутренние данные вектора (`items`, `capacity`, `size`) от одновременного доступа из разных потоков.

3. **Критическая секция (`portMUX_TYPE`)** — используется для атомарных операций со счётчиком ссылок и флагом удаления (на уровне одного ядра, без блокировки других ядер).

## Алгоритмы изменения ёмкости

### Увеличение ёмкости

- При первой вставке элемента начальная ёмкость устанавливается в **4 элемента**.
- При каждом последующем заполнении ёмкость удваивается (`capacity * 2`).
- Максимальная ёмкость ограничена значением `UINT16_MAX` (65 535).

### Уменьшение ёмкости

- Ёмкость уменьшается при удалении элемента, если:
  - `capacity > 4` и `capacity / 2 >= size * 2` (то есть выделенная память больше нужной более чем в 2 раза).
  - Новая ёмкость рассчитывается как `size * 2`, но не менее 4.
- При достижении `size == 0` вся память полностью освобождается.

## Примеры использования

### Базовый пример (целые числа)

```c
zh_vector_t *vector = NULL;
zh_vector_init(&vector, sizeof(int));

int val1 = 10, val2 = 20, val3 = 30;
zh_vector_push_back(vector, &val1);
zh_vector_push_back(vector, &val2);
zh_vector_push_back(vector, &val3);

// Получение элемента
int item_value = 0;
zh_vector_get_item(vector, 1, &item_value); // item_value = 20

// Изменение элемента
int new_val = 100;
zh_vector_change_item(vector, 1, &new_val); // элемент по индексу 1 теперь = 100

// Удаление элемента
zh_vector_delete_item(vector, 0); // удалён элемент со значением 10

// Очистка
zh_vector_free(&vector);
```

### Работа со структурами

```c
typedef struct {
    int id;
    char name[32];
    float value;
} my_struct_t;

zh_vector_t *vector = NULL;
zh_vector_init(&vector, sizeof(my_struct_t));

my_struct_t item1 = {1, "Item 1", 1.5f};
zh_vector_push_back(vector, &item1);

// Поиск по полю структуры
int search_id = 1;
int32_t found_index = -1;
my_struct_t sample = {0};
zh_vector_find_item_in_field(vector, &sample, &sample.id, sizeof(sample.id), &search_id, 0, &found_index);
// found_index = 0, так как элемент с id=1 находится по индексу 0

zh_vector_free(&vector);
```

## Логирование

Компонент использует ESP-IDF логирование с тегом `"zh_vector"`. Уровень логирования можно настроить:

```c
esp_log_level_set("zh_vector", ESP_LOG_ERROR); // только ошибки
```

## Ошибки

Все функции возвращают `esp_err_t`. Основные коды ошибок:

| Код | Описание |
|-----|----------|
| `ESP_OK` | Успех |
| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL-указатель, некорректный индекс и т.д.) |
| `ESP_ERR_INVALID_STATE` | Неверное состояние (вектор удаляется, мьютекс не получен) |
| `ESP_ERR_NO_MEM` | Не удалось выделить память |
| `ESP_ERR_NOT_FOUND` | Элемент не найден |

## Ограничения

1. **Максимум 65 535 элементов** — из-за использования `uint16_t` для индексов и ёмкости.
2. **Побайтовое сравнение** — `memcmp` сравнивает сырые байты, что может не учитывать выравнивание структур.
3. **Копирование данных** — все операции вставки и получения копируют данные, что может быть неэффективно для очень больших элементов.
4. **Зависимость от ESP-IDF** — компонент работает только в среде ESP-IDF с FreeRTOS.

## Требования для сборки

- ESP-IDF (фреймворк для ESP32)
- FreeRTOS (входит в состав ESP-IDF)
- Компонент должен находиться в директории `components/zh_vector` проекта

## Установка

Для добавления компонента в проект:

```bash
cd ваш_проект/components
git clone https://github.com/aZholtikov/zh_vector
```

Затем в коде подключить заголовочный файл:

```c
#include "zh_vector.h"
```