Αναζήτηση AST με προσωρινή μνήμη

Η αναζήτηση AST με προσωρινή μνήμη είναι μια συμπληρωματική λειτουργία με προθερμασμένη προσωρινή μνήμη για το ευρετήριο δεδομένων. Αντί να αποθηκεύει τα εξαγόμενα δεδομένα και να αναλύει ξανά τα αρχεία που αντιστοιχούν, αποθηκεύει στον δίσκο σειριοποιημένα δέντρα ανάλυσης. Τα επόμενα ερωτήματα αποσειριοποιούν τα δέντρα και εκτελούν απευθείας τον μηχανισμό αντιστοίχισης, παρακάμπτοντας εξ ολοκλήρου τη διαδικασία PHP-Parser.

Η προσωρινή μνήμη είναι διαθέσιμη μέσω της υποεντολής greph-index ast-cache CLI και των μεθόδων πρόσοψης Greph::buildAstCache() / Greph::searchAstCached(). Υποστηρίζει επίσης αναζήτηση σε πολλά ευρετήρια και σύνολα βάσει δηλωτικού αρχείου.

Δημιουργία της προσωρινής μνήμης

# Full build at the current directory
./vendor/bin/greph-index ast-cache build .

# Use a non-default cache directory
./vendor/bin/greph-index ast-cache build . --index-dir /tmp/greph-ast-cache

# Build a cache that may refresh automatically for small changes
./vendor/bin/greph-index ast-cache build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

Από προεπιλογή, η προσωρινή μνήμη αποθηκεύεται στο <root>/.greph-ast-cache/. Η δημιουργία της είναι συνήθως η πιο αργή από τις τρεις λειτουργίες ευρετηρίου, επειδή κάθε αρχείο πρέπει να αναλυθεί μία φορά.

Μια επιτυχής δημιουργία εκτυπώνει μια σύνοψη μίας γραμμής:

Built AST cache for 2547 files in .greph-ast-cache (2541 cached trees, +2541 ~0 -0 =0)

Ο αριθμός δέντρων στην προσωρινή μνήμη είναι συνήθως λίγο μικρότερος από τον αριθμό αρχείων, επειδή τα αρχεία που αποτυγχάνουν στην ανάλυση (και παραλείπονται σιωπηρά) δεν δημιουργούν καταχώριση στην προσωρινή μνήμη. Περάστε το --strict-parse στην εντολή αναζήτησης αν θέλετε να εμφανίζονται τα σφάλματα ανάλυσης.

Ανανέωση της προσωρινής μνήμης

./vendor/bin/greph-index ast-cache refresh .

Το refresh περιηγείται ξανά στη ρίζα του ευρετηρίου, αναλύει εκ νέου τα αρχεία που άλλαξαν και ξαναγράφει μόνο τα δέντρα στην προσωρινή μνήμη που μεταβλήθηκαν.

Τα προφίλ κύκλου ζωής είναι ίδια με εκείνα των άλλων λειτουργιών με προθερμασμένο ευρετήριο:

• static: μην ελέγχετε ποτέ αυτόματα την επικαιρότητα ούτε να κάνετε αυτόματες αλλαγές
• manual-refresh: αναφέρετε την παρωχημένη κατάσταση στο stats, αλλά μην ανανεώνετε ποτέ κατά την αναζήτηση
• opportunistic-refresh: ανανεώνετε κατά την αναζήτηση μόνο όταν το σύνολο των αλλαγών είναι κάτω από τα διαμορφωμένα όρια
• strict-stale-check: απορρίψτε τις παρωχημένες αναζητήσεις αντί να τις ανανεώσετε

Εκτέλεση ερωτημάτων στην προσωρινή μνήμη

./vendor/bin/greph-index ast-cache search 'new $CLASS()' src
./vendor/bin/greph-index ast-cache search '$obj->$method($$$ARGS)' src
./vendor/bin/greph-index ast-cache search --json 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --fallback scan 'new $CLASS()' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src

Το σύνολο σημαιών είναι ίδιο με εκείνο της ast-index search, μαζί με το --fallback scan για προσωρινές μνήμες που λείπουν.

Αναζήτηση σε πολλές προσωρινές μνήμες

Επαναλάβετε το --index-dir για αναζήτηση σε πολλές προθερμασμένες προσωρινές μνήμες με μία κλήση:

./vendor/bin/greph-index ast-cache search \
  --index-dir ../wordpress/.greph-ast-cache \
  --index-dir ./.greph-ast-cache \
  --show-index-origin \
  'array($$$ITEMS)' .

Σύνολα προσωρινής μνήμης βάσει δηλωτικού αρχείου

Αν διατηρείτε ήδη ονομασμένα προθερμασμένα σύνολα, το ίδιο δηλωτικό αρχείο μπορεί να χρησιμοποιηθεί για την αναζήτηση AST με προσωρινή μνήμη:

./vendor/bin/greph-index set build --mode ast-cache
./vendor/bin/greph-index set stats --mode ast-cache --dry-refresh
./vendor/bin/greph-index set search --mode ast-cache --show-index-origin 'array($$$ITEMS)' .

Διαγνωστικά σχεδιασμού

Το --trace-plan αναφέρει τις αποφάσεις του σχεδιασμού AST για την προσωρινή μνήμη στο stderr, όπως:

• ποια προθερμασμένα αποθηκευτικά μέσα αναζητήθηκαν
• αν εκτελέστηκε λογική ανανέωσης παρωχημένων δεδομένων
• πλήθος υποψήφιων αρχείων μετά τον περιορισμό σε επίπεδο αρχείου
• πόσα δέντρα από την προσωρινή μνήμη αποσειριοποιήθηκαν για ακριβή δομική αντιστοίχιση

Προσωρινή μνήμη ή ευρετήριο δεδομένων

Και οι δύο λειτουργίες επιταχύνουν την αναζήτηση AST, αλλά βελτιστοποιούνται για διαφορετικά είδη εργασίας.

Στην πράξη, το ευρετήριο γεγονότων προσφέρει το ταχύτερο κρύο ερώτημα, ενώ το cache το ταχύτερο θερμό ερώτημα. Χρησιμοποιήστε όποιο ταιριάζει στον φόρτο εργασίας σας ή δημιουργήστε και τα δύο και αφήστε τα εργαλεία σας να επιλέξουν.

Προγραμματιστική χρήση

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Index\IndexLifecycleProfile;

Greph::buildAstCache('.', lifecycle: IndexLifecycleProfile::Static);

$matches = Greph::searchAstCached(
    'array($$$ITEMS)',
    'src',
    new AstSearchOptions(jobs: 4, tracePlan: true),
);

Το searchAstCached δέχεται το ίδιο AstSearchOptions με την εγγενή αναζήτηση AST και επιστρέφει το ίδιο σχήμα list<AstMatch>. Η μόνη διαφορά είναι ότι παρακάμπτεται η ροή ανάλυσης για αρχεία που βρίσκονται ήδη στο cache. Για ροές εργασίας με πολλαπλά ευρετήρια ή με βάση manifest, χρησιμοποιήστε τα searchAstCachedMany(...) και searchAstCachedSet(...).

Πότε να το χρησιμοποιήσετε

Η λειτουργία AST με cache είναι η κατάλληλη όταν:

• Εκτελείτε επανειλημμένα δομικά ερωτήματα στην ίδια βάση κώδικα.
• Στις προηγούμενες εκτελέσεις, το σημείο συμφόρησης ήταν το PHP-Parser (στα προφίλ εμφανίζεται ως χρόνος που δαπανάται στον λεξικό αναλυτή και στον αναλυτή).
• Διαθέτετε αρκετό χώρο στον δίσκο για την αποθήκευση του σειριοποιημένου δέντρου.

Αν τα ερωτήματά σας αφορούν συνήθως ένα μικρό μέρος της βάσης κώδικα και οι αντιστοιχίες συγκεντρώνονται γύρω από αναγνωρίσιμα ονόματα κλήσεων ή κλάσεων, το ευρετήριο γεγονότων συνήθως ταιριάζει καλύτερα. Αν τα ερωτήματά σας καλύπτουν ευρέως τη βάση κώδικα, αλλά μπορείτε να επωμιστείτε το εφάπαξ κόστος ανάλυσης, υπερέχει το cache.