# Teljesítménymérések

A tárolóban a `bin/` és `benchmarks/` alatt található egy mérőeszköz. Minden keresési módot valós adathalmazokon (WordPress, Laravel) és generált szintetikus adathalmazokon mér, strukturált jelentéseket készít, és lehetővé teszi két jelentéssorozat összehasonlítását.

A mérőeszköz a tároló része, nem a Composer csomagé: mivel a 0.2.3, a `benchmarks/` és a `bin/bench*` parancsfájlok kimaradnak a csomagból, ezeket klónból futtassa (`git clone https://github.com/inline0/greph && cd greph && composer install`).

A [README](https://github.com/inline0/greph#performance) közzétett eredményei GitHub Actions futásokból származnak, soha nem helyi gépekről. A helyi futások hasznosak a fejlesztéshez; a hiteles forrást a CI-futások jelentik.

## Adathalmazok

A szintetikus adathalmazok (`synthetic-1k`, `synthetic-10k`, `synthetic-100k-single`) első futtatáskor a `benchmarks/corpora/synthetic/` alatt jönnek létre. A valós adathalmazok nincsenek mellékelve: helyezzen el egy klónt a `benchmarks/corpora/wordpress` vagy a `benchmarks/corpora/laravel` útvonalon (a CI-munkafolyamat a `--depth=1` használatával klónozza a `WordPress/WordPress` tárolót). A hiányzó könyvtárú adathalmazok kimaradnak.

## Mérések futtatása

```bash
# Full benchmark suite, every corpus that is present
./bin/bench

# Specific category (the category names used in benchmarks/suites/)
./bin/bench --category text
./bin/bench --category ast

# Compare against external tools when available
./bin/bench --compare rg,grep
./bin/bench --compare sg

# Choose a corpus
./bin/bench --corpus wordpress
./bin/bench --corpus laravel
./bin/bench --corpus synthetic-1k

# Write the run as JSON
./bin/bench --corpus wordpress --output build/run-1.json

# Measured series: 5 runs after 1 warmup run
./bin/bench-series --repeat 5 --warmup 1 --corpus wordpress --output build/head-series.json

# Aggregate separate runs into one series
./bin/bench-aggregate --output build/head-series.json build/run-*.json
```

A `bin/bench-compare base-series.json head-series.json` két sorozatfájlt hasonlít össze (az `bench-series` vagy az `bench-aggregate` kimenetét), és Markdown összefoglalót ír ki, ami hasznos egy gyakran használt kódrészlet fejlesztésekor. A `bin/bench-ci` elindítja a Benchmark munkafolyamatot a GitHub Actions rendszeren keresztül, a `gh` CLI használatával.

## Kategóriák

A README nyolc eredménycsoportot tesz közzé, amelyek mindegyike a motor egy meghatározott rétegét méri. Minden csoport a `benchmarks/suites/` fájlban meghatározott egy vagy több mérési kategóriát foglal magában.

### Pásztázási mód: szöveg

Natív szöveges keresés szó szerinti, reguláriskifejezés- és kombinált mintákkal. A közzétett alapmérés a WordPress adathalmazon fut, és a következőket tartalmazza:

- Szó szerinti `function`
- Kis- és nagybetűkre nem érzékeny szó szerinti keresés
- Teljes szavas szó szerinti keresés
- Új reguláris kifejezéspéldány
- Reguláris kifejezések tömbös hívása
- Reguláris kifejezés előtagjának szó szerinti keresése
- Reguláris kifejezés utótagjának szó szerinti keresése
- Reguláris kifejezés teljes sorának szó szerinti keresése
- Reguláris kifejezés szó szerinti részeinek összevonása

### Pásztázási mód: bejárás

Csak fájlbejárás, keresés nélkül. A gitignore-t figyelembe vevő bejáró önálló költségét méri.

### Pásztázási mód: párhuzamos szöveg

Rögzített karakterláncos keresés a következővel: `function`, `1`, `2` és `4` feladat. Ennél a mintánál a feldolgozócsoport csak `jobs * 4_000` fájl felett indul el (lásd: [Párhuzamos feldolgozók](https://greph.inline0.dev/hu/docs/advanced/parallel)), ami több, mint amennyit a WordPress adathalmaz tartalmaz, így mindhárom közzétett sor egyetlen folyamatban fut, és nem mutatja a feldolgozócsoport skálázódását ([#8](https://github.com/inline0/greph/issues/8)).

### Pásztázási mód: AST

Natív AST-keresés jellemző mintákkal:

- `new $CLASS()`
- `array($$$ITEMS)`

### Indexelt szöveges mód

Bemelegített indexelt szöveges keresés ugyanazokkal a mintákkal, mint a pásztázási mód. Szó szerinti, kis- és nagybetűkre nem érzékeny, teljes szavas, rövid tokenes és reguláriskifejezés-lekérdezéseket tartalmaz.

### Indexelt összesítő lekérdezések

Bemelegített indexelt szöveges keresés az egyezések számát, az egyezést tartalmazó fájlokat és az egyezést nem tartalmazó fájlokat visszaadó kimenetekkel. Ezek profitálnak a legtöbbet a találatokat tároló tárból, mert a fájlonkénti feldolgozás költsége a legalacsonyabb.

### Indexelt / gyorsítótárazott AST

Bemelegített AST-ténykeresés és gyorsítótárazott AST-keresés ugyanazokkal a mintákkal, mint az AST-pásztázási mód.

### Felépítési költségek

A háromgrammos index, az AST-tényindex és az AST-gyorsítótár hideg felépítésének költségei. Hasznos annak eldöntéséhez, hogy egy adott munkaterheléshez melyik módot érdemes fenntartani.

## A közzétett eredmények értelmezése

A README minden alapméréshez közzéteszi a legutóbbi CI-futás pillanatképét. Minden szakasz egy adott GitHub Actions futásból származik, és fel van címkézve az adathalmazzal, a futtatóval, az PHP verziójával, valamint a mérések és bemelegítések számával. Ha reprodukálni szeretne egy eredményt, helyben is ugyanezeket a feltételeket használja.

Az összehasonlító oszlopokat (`rg`, `grep`, `sg`) ugyanabban a feladatban, ugyanazon a futtatón, ugyanazon adathalmaz ellen gyűjtik. Ezeket nem külső mérésekből extrapolálják.

## Mérés hozzáadása

1. Adjon hozzá mérésdefiníciót a `benchmarks/` alatt.
2. Adjon hozzá egy megfelelő esetet a regressziós tesztcsomaghoz, ha még nincs hasonló (így a mérés alatt álló viselkedést is ellenőrzik).
3. Futtassa az `./bin/bench --category <yours>` parancsot az új mérés ellenőrzéséhez.
4. Hasonlítsa össze a `main` eredményével a Benchmark munkafolyamattal, amely azokra a lekéréses kérelmekre fut le, amelyek a `src/`, `benchmarks/` vagy `bin/` fájlokat érintik, és az összefoglalóban közli a legújabb és az alapverzió összehasonlítását.
5. Frissítse a README táblázatot, miután az új mérést tartalmazó CI-futás eredménye megjelent a `main` tárolón.

## Teljesítményfilozófia

A Greph nem arra törekszik, hogy hideg pásztázásokban megelőzze a ripgrep eszközt vagy a grep-et. A Ripgrep megvalósítása Rust nyelven készült, kézzel hangolt SIMD-szó szerinti kereséssel, és a közzétett eredmények szerint mind a `rg`, mind a GNU `grep` gyorsabb a Greph eszköznél minden hideg szöveges pásztázásban. A célok eltérnek:

- Legyen elég gyors ahhoz, hogy az interaktív használat és az ügynökciklusok natívnak érződjenek.
- A bemelegített indexekből válaszolja meg az ismétlődő lekérdezéseket: az indexelt reguláriskifejezés-, darabszám- és fájllista-lekérdezések gyorsabbak, mint amikor ugyanazt a fát a `rg` és a `grep` pásztázza.
- Előzze meg a `ast-grep` eszközt az indexelt és gyorsítótárazott AST-munkaterhelésekben, ahol a Greph meleg gyorsítótárai elkerülik a fa újbóli feldolgozását. A hideg AST-keresés vegyes eredményt ad: a `new $CLASS()` gyorsabb a `sg` eszköznél, a `array($$$ITEMS)` lassabb.
- Minden teljesítményjavulás legyen mérhető és reprodukálható.

A mérési jelentéssel alá nem támasztott teljesítményállításokat nem fogadjuk el.