# 3. Распределение работы между обработчиками

В этом руководстве вы запустите два обработчика с общей темой и увидите, как сервер распределяет между ними работу. Вы опубликуете шесть сообщений в `tasks`, и каждое попадёт ровно одному обработчику, а не обоим. Это **группа очереди** — пул подписчиков с общим именем, которые делят нагрузку.

**Движение сообщений — Группа очереди (анимация):** Анимация группы очереди: издатель отправляет сообщения, а NATS доставляет каждое ровно одному обработчику группы, распределяя нагрузку.

* Издатель → Обработчик 1
* Издатель → Обработчик 2
* Издатель → Обработчик 3

## Что понадобится

* Установленные `nats-server` и CLI `nats`. Если их ещё нет, сначала пройдите руководство [Привет, NATS](/tutorials/hello-nats.md).
* Четыре окна терминала: одно для сервера, два для обработчиков и одно для публикации.

## Шаг 1: запустите сервер

В первом терминале запустите `nats-server`:

```
nats-server
```

Журнал запуска должен заканчиваться строкой о готовности:

```
[INF] Server is ready
```

Оставьте сервер работающим.

## Шаг 2: запустите первый обработчик

Во втором терминале подпишитесь на тему `tasks` как участник группы очереди `workers`. Именно флаг `--queue` делает подписчика участником группы очереди, а не обычным подписчиком:

#### CLI

```
#!/bin/bash

# Подпишитесь на тему "tasks" как участник группы очереди "workers".

# Параметр --queue задаёт имя группы. Подписчики одной и той же

# группы в одной теме разделяют нагрузку: каждое сообщение доставляется

# ровно одному участнику. Запустите команду в двух терминалах, чтобы увидеть

# распределение заданий. Для остановки нажмите Ctrl-C.

nats sub tasks --queue workers
```

#### C

```
// The callback runs once for each task the server hands this worker.

static void

onTask(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)

{

    printf("received on \"%s\": %.*s\n",

           natsMsg_GetSubject(msg),

           natsMsg_GetDataLength(msg), natsMsg_GetData(msg));

    natsMsg_Destroy(msg);

}

    // Subscribe to the "tasks" subject as a member of the "workers" queue

    // group. Every subscriber that names the same group on the same subject

    // shares the load: each message is delivered to exactly one member.

    // Run this program twice to watch work split between the two copies.

    if (s == NATS_OK)

        s = natsConnection_QueueSubscribe(&sub, conn, "tasks", "workers",

                                          onTask, NULL);
```

Обработчик должен перейти в ожидание сообщений:

```
17:42:10 Subscribing on tasks
```

Оставьте его работающим.

## Шаг 3: запустите второй обработчик

В третьем терминале выполните ту же команду. Поскольку в ней указаны та же группа очереди `workers` и та же тема `tasks`, обработчик присоединится к той же группе:

#### CLI

```
#!/bin/bash

# Подпишитесь на тему "tasks" как участник группы очереди "workers".

# Параметр --queue задаёт имя группы. Подписчики одной и той же

# группы в одной теме разделяют нагрузку: каждое сообщение доставляется

# ровно одному участнику. Запустите команду в двух терминалах, чтобы увидеть

# распределение заданий. Для остановки нажмите Ctrl-C.

nats sub tasks --queue workers
```

#### C

```
// The callback runs once for each task the server hands this worker.

static void

onTask(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)

{

    printf("received on \"%s\": %.*s\n",

           natsMsg_GetSubject(msg),

           natsMsg_GetDataLength(msg), natsMsg_GetData(msg));

    natsMsg_Destroy(msg);

}

    // Subscribe to the "tasks" subject as a member of the "workers" queue

    // group. Every subscriber that names the same group on the same subject

    // shares the load: each message is delivered to exactly one member.

    // Run this program twice to watch work split between the two copies.

    if (s == NATS_OK)

        s = natsConnection_QueueSubscribe(&sub, conn, "tasks", "workers",

                                          onTask, NULL);
```

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

```
17:42:18 Subscribing on tasks
```

Теперь в группе два обработчика. Оба терминала ожидают: сообщений пока не было.

## Шаг 4: опубликуйте задания

В четвёртом терминале опубликуйте шесть сообщений в `tasks`. Флаг `--count` повторяет публикацию шесть раз, а CLI заменяет `{{ Count }}` номером сообщения:

#### CLI

```
#!/bin/bash

# Опубликуйте шесть сообщений в теме "tasks". Параметр --count повторяет

# публикацию указанное число раз, а {{ Count }} заменяется номером сообщения

# (1, 2, 3, ...). Если в группе очереди "workers" два обработчика,

# сервер передаёт каждое сообщение ровно одному из них.

nats pub tasks "task {{ Count }}" --count 6
```

#### C

```
// Publish six messages to the "tasks" subject. With two workers in

// the "workers" queue group, the server hands each message to

// exactly one of them.

char task[32];

int  i;



for (i = 1; (s == NATS_OK) && (i <= 6); i++)

{

    snprintf(task, sizeof(task), "task %d", i);

    s = natsConnection_PublishString(conn, "tasks", task);

    if (s == NATS_OK)

        printf("published \"%s\" to \"tasks\"\n", task);

}
```

Издатель должен вывести по одной строке подтверждения на сообщение:

```
17:42:30 Published 6 bytes to "tasks"

17:42:30 Published 6 bytes to "tasks"

17:42:30 Published 6 bytes to "tasks"

17:42:30 Published 6 bytes to "tasks"

17:42:30 Published 6 bytes to "tasks"

17:42:30 Published 6 bytes to "tasks"
```

## Шаг 5: посмотрите на распределение

Посмотрите на терминалы двух обработчиков. Шесть сообщений распределены между ними: каждый получает часть, и ни одно сообщение не появляется в обоих терминалах. Один терминал может показать:

```
[#1] Received on "tasks"

task 1



[#2] Received on "tasks"

task 3



[#3] Received on "tasks"

task 5
```

а другой:

```
[#1] Received on "tasks"

task 2



[#2] Received on "tasks"

task 4



[#3] Received on "tasks"

task 6
```

Для каждого сообщения сервер выбирает одного участника, поэтому точное распределение меняется. Неизменно одно: каждое сообщение получает ровно один обработчик.

Повторите публикацию, чтобы ещё раз увидеть распределение:

#### CLI

```
#!/bin/bash

# Опубликуйте шесть сообщений в теме "tasks". Параметр --count повторяет

# публикацию указанное число раз, а {{ Count }} заменяется номером сообщения

# (1, 2, 3, ...). Если в группе очереди "workers" два обработчика,

# сервер передаёт каждое сообщение ровно одному из них.

nats pub tasks "task {{ Count }}" --count 6
```

#### C

```
// Publish six messages to the "tasks" subject. With two workers in

// the "workers" queue group, the server hands each message to

// exactly one of them.

char task[32];

int  i;



for (i = 1; (s == NATS_OK) && (i <= 6); i++)

{

    snprintf(task, sizeof(task), "task %d", i);

    s = natsConnection_PublishString(conn, "tasks", task);

    if (s == NATS_OK)

        printf("published \"%s\" to \"tasks\"\n", task);

}
```

Новая партия так же распределяется между двумя обработчиками. Нажмите Ctrl-C в каждом терминале для остановки.

## Что вы создали

Два обработчика совместно подписались на тему `tasks` через группу очереди `workers`, и сервер доставил каждое сообщение только одному из них. Добавьте третий обработчик той же командой: размер группы изменится автоматически, а работа распределится между тремя без дополнительных настроек.

## Дальше

* Создайте поток, который сохраняет сообщения для последующего чтения обработчиком: [Первый поток](/tutorials/first-stream.md).
* Узнайте, как сервер выбирает участника, как меняется состав групп во время работы и когда нужна долговременная очередь заданий: [Углублённое изучение групп очередей](/learn/core-nats/queue-groups.md).
