Sprinter-SDCC/docs/file-buffering-design.md

FILE*: буферизация — анализ solid-c и варианты (2026-07-06)

Статус: вариант B+ РЕАЛИЗОВАН 2026-07-06 (решение пользователя). Единый ленивый буфер BUFSIZ=512 на чтение/запись с автопереключением направления (_F_DIROUT), статическая таблица OPEN_MAX=8 слотов (без malloc для FILE), _fclosall через atexit, ungetc через hold, fprintf/vfprintf через vsprintf+fwrite, fflush(NULL) = все потоки. Внутренности: libc/file/_file.h (+_file_sync/_file_buf/_file_slots/ _fclosall). Фактическая цена: filetest 7411→9929 Б _CODE (доля только-читающих потребителей ~+1.3 КБ, включая malloc); программы без FILE* не платят. Верификация: MAME filetest + fdmax + fbench. Ниже — исходный анализ, на основании которого принималось решение.

Как сделано в solid-c (SRC/CLIB/STDIO.ASM)

Структура FILE — 14 байт, статический массив _iob[8] (без malloc для самих FILE; псевдопотоки stdout/stderr/stdaux/stdprn лежат ПЕРЕД массивом и адресуются отрицательными индексами — трюк, нам не нужен):

flags(2), level(2), curp(2), fd(2), buffer(2), hold(1), token(2), dummy(1)

Механика:

• Буфер 512 Б, ленивый malloc при первом буферизуемом fgetc/fputc (флаг _F_BUF = «буфер наш, free при fclose»). Программа без файлового I/O не платит ничего.
• Чтение (_fgetc): level == 0 → read(fd, buffer, 512), curp = buffer; отдача — *curp++, level--; ставится _F_IN.
• Запись (_fputc): *curp++ = c, level++; при level == 512 — fflush (один write всего буфера); ставится _F_OUT.
• Полудуплекс: fputc при взведённом _F_IN — ОШИБКА (не авто-flush); направление сбрасывает только fflush.
• fflush входного потока: lseek(fd, -level, SEEK_CUR) — откат непрочитанного readahead, буфер инвалидируется. Выходного — write(buffer, level).
• fseek/ftell = fflush + голый lseek/ltell по fd (после flush позиция fd совпадает с логической позицией потока).
• ungetc: буфер не пуст → *--curp = c; пуст/отсутствует → символ в поле hold, curp указывает на hold.
• fclosall через atexit — сброс буферов при exit.
• Консольные потоки минуют буфер (RST-вызовы напрямую).
• fread/fwrite — ПОБАЙТОВЫЙ цикл через _fgetc/_fputc: большие блоки платят call+IY-доступ за каждый байт. Это слабое место порта.

Варианты для нас

A. Полный порт solid-c (буфер на чтение и запись). Плюсы: ускоряются и писатели через fputc/fprintf. Минусы: полудуплекс («запись после чтения без fflush — ошибка») — источник тонких багов; обязателен flush в exit (сцепка atexit+file); больше кода во всех модулях; наши блочные fread/fwrite пришлось бы защищать от деградации.

B. Буферизовать ТОЛЬКО чтение (рекомендую). FILE += buf(2), level(2), curp(2), hold(2); буфер 512 Б лениво.

• fgetc: hold → буфер → refill. fgets остаётся циклом по fgetc (теперь дешёвым).
• fread: сначала хвост буфера (memcpy), остаток ≥ 512 — прямой read() в ptr одним syscall (обходя буфер), мелкий остаток — refill.
• Запись НЕ буферизуется — как сейчас: fputc = write(1 байт), fputs/fwrite = один write() на блок. Нечего терять при аварии, fflush остаётся no-op по данным, полудуплекса нет.
• Согласование позиций: перед write/fseek/ftell на потоке с readahead — lseek(fd, -(level), SEEK_CUR) + инвалидация буфера (один общий хелпер _file_sync). ftell = lseek(0,CUR) − level (без syscall не выйдет — lseek и так syscall).
• ungetc: через hold, работает и до первого заполнения буфера.

Плюсы: решает главную боль (парсеры), запись остаётся простой и надёжной, никакого flush-on-exit, r+ работает через _file_sync. Минусы: fputc-писатели остаются медленными (редкий паттерн — fputs/ fwrite блочные и так быстрые).

B+. Единый буфер на чтение И запись с АВТОпереключением направления (предложение 2026-07-06, кандидат в целевой дизайн). Схема solid-c, но без ловушки: направление переключает сама библиотека.

• флаг направления в FILE: буфер сейчас «readahead» или «накопитель записи»;
• fputc при направлении «чтение»: _file_sync (отмотка fd на -level, буфер пуст) → режим записи → накопление; сброс write() при заполнении;
• fgetc при направлении «запись»: flush (write(buf, level)) → режим чтения → refill;
• fwrite больших блоков: flush + прямой write мимо буфера; мелких — memcpy в буфер. fread симметрично;
• fseek/ftell/fclose: flush-или-sync по направлению; ftell = позиция fd − level (чтение) / + level (запись);
• обязателен реестр открытых потоков: поле next в FILE (регистрация в fopen, снятие в fclose) + _fclosall через atexit — стандарт требует flush всех потоков в exit(); без этого fputs(...); exit(1); теряет данные;
• цена-семантика: ошибки записи становятся ОТЛОЖЕННЫМИ (вылезают при flush/fclose, не в момент fputc) — проверять результат fclose;
• цена-код: ~+350–500 Б против ~+200–300 у B (тянется только использующими FILE*).

C. Оставить небуферизованным («большие файлы читаются целиком в EMM», паттерн mdview). Для приложений-парсеров среднего размера неудобно; отвергается самим существованием П2-пункта.

D. Полная стандартная буферизация + setvbuf — отвергнуто ранее решением file_star_design (минимальный FILE*).

Что взять у solid-c при варианте B

• ленивый malloc 512 Б + флаг «буфер наш»;
• откат readahead lseek'ом (механика их fflush-на-вход) — как _file_sync перед write/fseek/ftell;
• ungetc с hold-байтом;
• консольные потоки мимо буфера (у нас уже так).

Чего НЕ брать: побайтовые fread/fwrite, полудуплекс, статический _iob[] с отрицательными индексами, буферизацию записи.

Лимит открытых файлов и статическая таблица FILE (2026-07-06)

Факты: solid-c — OPEN_MAX = 8, статический массив из 8 FILE-структур (+5 псевдопотоков перед ним), fdopen отвергает fd > 8. DSS-доки: FCB строятся «в рабочих областях ДОС», код ошибки 06h = «Too many open files» (наш EMFILE = 6 совпадает).

ПОДТВЕРЖДЕНО тестом fdmax (MAME, DSS 1.71.57, 2026-07-06): пользователю доступно 8 манипуляторов, fd 2..9 (fd 1 держит шелл DSS под запущенный .exe). КРИТИЧНО: 9-й OPEN не возвращает 06h — он ВЕШАЕТ систему. Поэтому в libc/io добавлен предохранитель _fd_guard (счётчик в open/close, отказ EMFILE на 9-м open без захода в DSS) — таблица fopen и guard вместе закрывают и высокий, и низкий уровень.

Следствие для B+: вместо malloc-FILE + связного списка-реестра — статическая таблица из 8 слотов (свободный слот: flags == 0):

• реестр для flush-on-exit бесплатен: _fclosall = цикл по таблице;
• fopen без malloc — единственный отказ синхронен с отказом DSS (EMFILE), утечка «fclose без free» невозможна;
• цена: ~112–128 Б BSS (в exe не входит), только у программ с fopen;
• буферы НЕ статические — остаются ленивыми malloc 512 Б (потолок 8×512 = 4 КБ heap в худшем случае);
• объявить FOPEN_MAX 8 в stdio.h; если fdmax покажет лимит DSS < 8 — уменьшить таблицу.

Семантика инвалидации (вариант B) — контрольный сценарий

Буфер — только кэш опережающего чтения. Правило: любая запись и любой fseek обнуляют буфер; запись всегда идёт напрямую в файл после отмотки позиции (_file_sync: lseek(fd, -level, SEEK_CUR) + level = 0). Буфер при записи НЕ патчится — write-through с правкой окна отвергнут как сложный ради редкого паттерна.

Сценарий «r+, чтение-запись-чтение» (обсуждено 2026-07-06): read 512 в буфер → 10×fgetc (логическая поз. 10, fd на 512) → первый fputc: sync отматывает fd на 10, буфер пуст, 10×write ложатся на 10..19 → fseek(0) → fgetc перечитывает буфер С ДИСКА и видит записанные байты. Протечка старой копии невозможна — она уничтожена в момент первой записи.

Оценка/проверка

Бенчмарк до/после: цикл fgets по tests/seek/big.txt с замером ptime (тест tests/fbench), плюс filetest-регресс в MAME. Ожидание: чтение ~512× меньше syscall'ов; код file-модулей +200–300 Б (тянется только использующими FILE*).