xretractor

Program xretractor jest podstawowym procesem systemu RetractorDB. Kompiluje pliki z zapytaniami RQL i realizuje plan przetwarzania danych. Przygotowany jest do uruchomienia autonomicznego jako proces demona systemd.

Tryby pracy

xretractor uruchamia się w jednym z dwóch trybów:

Wywołanie -h pokazuje inną listę opcji w zależności od trybu - skróty opcji się nakładają, dlatego należy zwrócić uwagę, w którym trybie dana opcja funkcjonuje.

Tryb przetwarzania (domyślny)

$ xretractor -h
xretractor - compiler & data processing tool.

Usage: xretractor queryfile [option]

Available options:
  -h [ --help ]               Show program options
  -b [ --build-info ]         show optimizer build configuration
  -c [ --onlycompile ]        compile only mode
  -q [ --queryfile ] arg      query set file
  -r [ --quiet ]              no output on screen, skip presenter
  -s [ --status ]             check service status
  --cleanup                   remove leftovers of dead instances and exit
  -v [ --verbose ]            verbose mode (show stream params)
  -x [ --xqrywait ]           wait with processing for first query
  -n [ --name ] arg           instance name; own IPC area and lock
  -a [ --autoname ]           generate a docker-style instance name
  -k [ --noanykey ]           do not wait for any key to terminate
  -j [ --service ]            service mode: log to stderr (journald)
  -t [ --realtime ]           enable real-time scheduling
  -f [ --no-clock ]           offline mode: compute slots without waiting
  -u [ --until-eof ]          forces one-shot all sources
  -g [ --config ] arg         config file (TOML); overrides search
  -m [ --llimitqry ] arg (=0) loop iteration limit, 0 - no limit

Opcje trybu przetwarzania

Wiele instancji

Różne nazwane instancje mogą działać równocześnie:

xretractor pomiary.rql --name pomiary --noanykey &
xretractor diagnostyka.rql --name diagnostyka --noanykey &
xqry --bus

Każda otrzymuje własną blokadę i zestaw obiektów IPC. Wspólna magistrala odrzuca jednak plan, który koliduje z żywą instancją nazwą strumienia, zapisywanym plikiem magazynu albo plikiem licznika :ROTATION. Kontrola odbywa się przed usuwaniem artefaktów. Brak --name zachowuje historyczną instancję bezimienną.

Tryb usługowy stanowi osobną gwarancję: w każdej przestrzeni RDB_NAMESPACE może działać dokładnie jedna instancja usługowa, w domyślnej przestrzeni nazwana service. Szczegóły zawiera rozdział Wiele instancji i magistrala.

Sprzątanie pozostałości

xretractor --cleanup

Polecenie nie uruchamia planu. Próbuje zająć blokady rozpoznanych zasobów i usuwa wyłącznie te, których nie utrzymuje żywy właściciel. Ten sam mechanizm działa przy wyjściu instancji.

Zakres nie jest ograniczony do jednej instancji wskazanej przez --name ani jednej przestrzeni RDB_NAMESPACE. Dostęp do zasobów nadal podlega uprawnieniom systemu plików. Polecenie nie wylicza i nie usuwa kolejek odpowiedzi klientów; nie usuwa też segmentów v5 i starszych, które nie uczestniczą w protokole blokady obecności.

Wynik zawiera liczniki usuniętych blokad instancji, zestawów tożsamości IPC i segmentów, np.:

Removed leftovers of dead instances: 1 instance lock(s), 1 IPC identity set(s), 1 bus segment(s).

Licznik zestawów IPC nie jest liczbą pojedynczych kolejek. Zakończenie polecenia nie dowodzi usunięcia zasobów spoza jego zakresu. Przy niestandardowym katalogu blokad należy wskazać właściwy TOML przez --config.

Przetwarzanie wsadowe bez zegara

Najprostszy przebieg całego pliku bez ręcznego dobierania liczby iteracji ma postać:

xretractor query.rql --no-clock --until-eof --noanykey --quiet

--no-clock usuwa wyłącznie uśpienia. Nie zmienia kolejności slotów ani zawartości artefaktów, dlatego nadaje się do szybkiej weryfikacji po zakończeniu procesu. Może jednak wyprzedzić klienta xqry, więc nie jest właściwym trybem do obserwacji na żywo.

--until-eof sprawia, że źródło sekwencyjne nie wraca na początek pliku. Koniec jest sprawdzany po przetworzeniu slotu, dokładnie przed rekordem, który musiałby już powstać ze syntetycznego NULL za końcem danych. Przy wielu źródłach kończy pierwsze wyczerpane, aby plan nie kontynuował obliczeń z brakującym wejściem. Opcję można łączyć z -m N; działa warunek, który wystąpi wcześniej.

⚠️ Ostrzeżenie Skróty zależą od trybu. W wykonaniu -f oznacza --no-clock, a -u oznacza --until-eof. Przy -c te same litery oznaczają odpowiednio --fields i --rules oraz nie uruchamiają przetwarzania.

NOTE: Równoważność wykonania taktowanego i offline sprawdza noclock_offline, a zatrzymanie na pierwszym końcu danych i kontrolę zawijania sprawdza untileof_stop.

Tryb tylko kompilacja (-c)

$ xretractor -h -c
xretractor - compiler & data processing tool.

Usage: xretractor -c queryfile [option]

Available options:
  -h [ --help ]          show help options
  -b [ --build-info ]    show optimizer build configuration
  -c [ --onlycompile ]   compile only mode
  -q [ --queryfile ] arg query set file
  -r [ --quiet ]         no output on screen, skip presenter
  -d [ --dot ]           create dot output
  -m [ --csv ]           create csv output
  -f [ --fields ]        show fields in dot file
  -t [ --tags ]          show tags in dot file
  -s [ --streamprogs ]   show stream programs in dot file
  -u [ --rules ]         show rules in dot file
  -i [ --hideruleprog ]  hide rule program in rules (-u) output
  -p [ --transparent ]   make dot background transparent
  -w [ --diagram ] arg   create diagram output
  -z [ --shmbudget ]     show shared memory budget of the compiled plan

W tym trybie dostępne są opcje tworzenia diagramów i zrzutów diagnostycznych opisywanych szerzej w opracowaniu.

Opcje wizualizacji i diagnostyki

Plik konfiguracyjny (TOML)

Opcja --config wskazuje plik konfiguracyjny; bez niej program przeszukuje warstwowo dwie lokalizacje, w podanej kolejności, a każda kolejna warstwa nadpisuje klucze poprzedniej:

1. /etc/retractor/retractor.toml - warstwa systemowa,
2. $XDG_CONFIG_HOME/retractor/retractor.toml (lub ~/.config/retractor/retractor.toml) - warstwa użytkownika.

Brak plików jest stanem poprawnym - program startuje z wartościami domyślnymi. Błąd składni TOML w warstwie wyszukiwanej powoduje ostrzeżenie i pominięcie tej warstwy; przy jawnie podanej ścieżce (--config) brak pliku lub błąd składni są twarde, bo stanowią jawne żądanie użytkownika. Ten sam plik czyta również xqry (pod skrótem -e), dlatego sekcje [ipc] i [timing] dotyczą obu procesów.

Wartości spoza sensownego zakresu nie zatrzymują usługi: program zapisuje ostrzeżenie w dzienniku i używa wartości domyślnej. Wyjątkiem jest storage.dir, którego niepoprawność jest błędem twardym - wskazywałaby, że wyniki trafiłyby w niezamierzone miejsce lub nigdzie.

Przykładowy plik:

[storage]
dir = "/var/lib/retractor"

[ipc]
queue_buffer_seconds = 30

[scheduling]
rt_priority = 60

[paths]
lock_dir = "/var/run/retractor"

[server]
autoname = false

NOTE: Wczytywanie warstw i walidację pokrywa test jednostkowy ut_appConfig; twarde odrzucenie niepoprawnego storage.dir - test integracyjny config_storage_validation.

Usługa i wymiana planu

Start bez pliku .rql albo z pustym plikiem tworzy bezczynną instancję z działającym IPC. Pierwszy lub kolejny pełny plan można załadować bez restartu:

xqry --server service --reset plan.rql

Serwer parsuje i kompiluje całą treść, sprawdza kolizje zasobów, rezerwuje nowy zestaw, a następnie przełącza plan na granicy slotu. Odmowa pozostawia poprzedni plan bez zmian. Pusty plik resetu przywraca stan bezczynny. W instancji usługowej zaakceptowana treść jest również zapisywana w pliku startowym usługi.

Alternatywna ścieżka xretractor nowy-plan.rql wykrywa działającą jednostkę systemd, weryfikuje zestaw, atomowo nadpisuje jej plik startowy i wywołuje restart. Jawne wskazanie innej tożsamości przez --name albo --autoname oznacza zamiast tego start osobnej instancji. W razie krytycznego błędu plan usługowy jest opróżniany, aby systemd uruchomił proces ponownie w bezpiecznym stanie bezczynnym.

Informacje o wersji

Na końcu każdego komunikatu pomocy wyświetlana jest linia z informacjami o buildzie:

Branch: issue_31-doc:2707ce0,
Code compiler: GNU Ver. 13.3.0,
Build time: 2512211449,
Type: Debug

Kolejna linia wskazuje lokalizację pliku dziennika:

Log: /tmp/xretractor.log

Plik /tmp/xretractor.log rejestruje historię wywołań i zdarzeń wewnętrznych systemu. W środowisku produkcyjnym należy zadbać o regularne czyszczenie lub rotację tego pliku.

Ostatnia linia zawiera informację o licencji MIT, która umożliwia bezpieczne użycie kodu w zastosowaniach korporacyjnych.