Глава 1 Том 1 · Начало и ядро: введение

Ориентация главы

Том 1 — фундамент всей книги. Что бы вы ни писали на XRT — сетевые сервисы, разбор конфигурации или защищённые соединения — каждая ваша строка стоит на содержании этого тома: как сообщаются ошибки (глава 4), как память выделяется и возвращается (глава 5), как внедряются сбои для локализации проблем (глава 6), как временные объекты управляются без накладных расходов (глава 7) и насколько мелкой может быть обрезка по потребности (глава 8). Это не «продвинутые возможности», а общебиблиотечный язык: каждая следующая глава использует эти правила напрямую и не объясняет их второй раз.

Карта знаний тома и порядок чтения:

Рекомендуемые пути для трёх типов читателей: начинающим в C — читать подряд и самостоятельно компилировать и запускать каждую полную программу главы; программы в этом томе короткие, но каждую стоит запустить. Читателям с инженерным опытом на C — быстро пройти главы 2 и 3 и вложить время в главу 4 (модель ошибок — одна из самых своеобразных находок XRT) и главу 6 (внедрение сбоев — основа методики тестирования последующих глав о сетях и TLS). Пришедшим из других языков — обратить особое внимание на концепцию «представления» в главе 3 и соглашения владения в главе 5: это C-аналоги срезов строк и умных указателей соответственно, но с более строгими правилами.

Соглашения об именах и терминологии

Прежде чем читать код XRT, договоримся о правилах «вижу имя — понимаю смысл», действующих во всей книге. Функции и типы используют префикс модуля + UpperCamelCase: имена на xrt — функции ядра (xrtJsonParse — функция разбора модуля json), короткие имена на строчную x — типы (xerror, xstrview), имена из заглавных на X — константы и макросы (XERR_TIMEOUT, XRT_NPOS). Имена параметров несут венгерские префиксы: p — указатель, i — целое, s — строка с нулевым завершителем, b — булево, arr — массив, Text/View — представление: увидев pConfig и iCount, вы знаете тип, не возвращаясь к объявлению. Выходные параметры почти всегда указательные (в C нет ссылок), и функция не пишет в них при отказе — «отказ без побочных эффектов» избавляет код восстановления от уборки полуфабрикатов.

Три термина, которые будут повторяться, зафиксируем сразу: владение (own) означает «вы отвечаете за освобождение, ровно один раз»; заимствование (borrow) означает «можно использовать, но освобождать нельзя, время жизни следует за источником»; управление означает, что объект несёт собственный механизм жизненного цикла (подсчёт ссылок или владеющий пул) — вы увеличиваете и уменьшаете доли по правилам, а не распределяете и освобождаете напрямую. Представления главы 3 — носитель заимствования; глобальная куча главы 5 — выход владения; подсчёт ссылок — реализация управления. Трое образуют скелет повествования XRT о памяти.

Самопроверка обучения

После каждой главы задавайте себе три вопроса: какую задачу решила глава (можете сказать коллеге одним предложением?); какие жёсткие правила перечислены в разделе контрактов (можете воспроизвести с закрытой книгой?); находите ли вы тени симптомов из раздела ловушек в своём прошлом коде? Если все три ответа получились — идите дальше; если один застрял — перечитайте тот раздел: этот том — фундамент, и этажи выше за вас его не достроят. Этот чек-лист — также метод обучения всей книги: каждый модуль XRT стоит прожевать тройкой «задача, контракт, ловушка»; когда привычка сложится, чтение любого нового модуля заметно ускорится.

Как пользоваться книгой

Структура каждой главы фиксирована: ориентация говорит, где глава стоит и куда ведёт; введение исходит из реальной задачи, а не из списка API; понятия строят ментальные модели со схемами состояний или потоков; примеры — полные компилируемые программы, каждая с командой сборки и реальным выводом, большинство взято прямо из каталога examples/ репозитория (в углу каждого блока кода есть ссылка на исходник с переходом на Gitee для сравнения); контракты собирают жёсткие правила об ошибках, владении и потоках; ловушки дают симптомы, причины и пары неверный/верный код; упражнения трёхуровневые — базовые, продвинутые и вызов. Рекомендуемый ритм чтения: сначала прочитайте понятия и примеры, затем сами запустите программы и наконец выполните хотя бы базовые упражнения — только после этих трёх шагов знание главы оседает.

Встретив незнакомую функцию, есть два входа: в конце каждой главы блок «справочники API в этой главе» ведёт прямо на полную справочную страницу модуля (сигнатуры, ограничения параметров, возвращаемые значения, ошибки, примеры); или откройте страницу поиска API на сайте и введите имя функции. Справочные страницы и книга питаются одними и теми же фактами и никогда не расходятся.

Подготовка к чтению

Нужны только две вещи: компилятор C11 (подходит GCC/Clang/MSVC; примеры книги даются по выводу Windows + GCC, на других платформах вывод идентичен или отличия оговорены) и копия исходников XRT — git clone https://gitee.com/xywhsoft/xrt.git или скачайте архив напрямую. Заранее устанавливать сторонние библиотеки не нужно: рантайм XRT не имеет сторонних зависимостей, примеры используют только стандартную библиотеку C. Команды сборки всех примеров приведены в блоках вывода соответствующих глав — скопируйте и запустите; держите корень репозитория рабочим каталогом, чтобы относительные пути в командах (вроде -I single, examples/...) разрешались корректно.

Маршрут книги

После тома 1: тома 2–5 — половина «данные и системы»: математика и случайности, контейнеры, текст и структурированные данные, логирование и файлы/процессы; тома 6–9 — половина «конкурентность и сети»: потоки и корутины, сети, безопасность и ядро веб-протоколов; тома 10 и 11 — пять библиотек расширений; том 12 возвращается к инженерной перспективе (сборка, обрезка, тесты, производительность); том 13 собирает книгу воедино пятью полными проектами. Вступление каждого тома даёт его карту знаний и пререквизиты — если пререквизит какого-то тома ещё не прочитан, вступление прямо укажет на соответствующие главы.

К концу тома 1 вы должны без подглядывания отвечать: что возвращает падающая XRT-функция и где читать подробности ошибки; откуда берётся блок памяти и кто его освобождает; какая линия обороны подстраховывает недоверенный ввод; и какой единственной строкой макросов обрезать XRT до нужных модулей. Выходите в путь с этими вопросами.