landmarks
v1.4
Landmarks ist eine einfache Profilbibliothek für OCAML. Es bietet Primitiven, Teile des Codes abzugrenzen und die Leistung von instrumentierten Code zur Laufzeit zu messen. Die verfügbaren Kennzahlen werden durch Aggregation von CPU -Zyklen (unter Verwendung des Zeitstempelzählers der CPU), der Anwendungszeit (unter Verwendung von Sys.time ) und zugewiesenen Bytes (mit Gc.allocated_bytes ) erhalten. Die Instrumentierung des Codes kann entweder von Hand, automatisch oder halbautomatisch mit einer PPX-Erweiterung erfolgen.
Während der Ausführung Ihres Programms wird der Durchlauf des instrumentierten Codes durch den Steuerfluss als "Callgraph" aufgezeichnet, der die gesammelten Maßnahmen ausführt. Die Ergebnisse können entweder direkt auf der Konsole oder nach JSON exportiert werden.
Dieses Tool soll verwendet werden, um herauszufinden, wo die Zeit in Ihren Programmen verbracht wird (und nicht unabhängige Codesteile wie Core_Bench), während sie Ergebnisse liefern Arbeiten Sie direkt mit der binären ausführbaren Datei wie Gprof oder Perf).
Für weitere Informationen können Sie die API durchsuchen.
Die Bibliothek ist in zwei Pakete aufgeteilt: landmarks für die Laufzeitbibliothek und landmarks-ppx für den Präprozessor, der automatische Instrumente implementiert.
opam install landmarks
oder
opam install landmarks-ppx
installiert entweder die Laufzeitbibliothek oder sowohl die Laufzeitbibliothek als auch die Präprozessorin.
git clone https://github.com/LexiFi/landmarks.git
cd landmarks
dune build @install
Verwenden Sie einfach die landmarks der Bibliothek und die Vorverhandlungen an den landmarks-ppx um Ihre ausführbaren Funktionen und Bibliotheken zu bewerten. Beispielsweise erstellt die folgende dune -Datei den ausführbaren test mit der landmarks -Bibliothek und ihrer PPX. Die optionale Flagge --auto , schaltet die automatische Instrumentierung ein (siehe unten).
(executable
(name test)
(libraries landmarks)
(preprocess (pps landmarks-ppx --auto))
)
Es ist möglich, Dune zu verwenden, um die Instrumentierung eines Projekts automatisch auszulösen. Schauen Sie sich Lexifi/Landmarken-Starter für ein grundlegendes Beispiel an und finden Sie im Dune-Handbuch für weitere Informationen.
ocamlfind ocamlopt -c -package landmarks prog.ml
ocamlfind ocamlopt -o prog -package landmarks -linkpkg prog.cmx
Sie können "ocamlopt" durch "ocamlc" ersetzen, um das Programm in Bytecode zu kompilieren.
ocamlfind ocamlopt -c -package landmarks -package landmarks-ppx -ppxopt landmarks-ppx,--auto prog.ml
ocamlfind ocamlopt -o prog -package landmarks -linkpkg prog.cmx
Beachten Sie, dass "-PPXOPT Sehensmarks-PPX,-Auto" optional ist und die automatische Instrumentierung einschalten.
Es gibt drei Hauptimitive:
val register : string -> landmark
val enter : landmark -> unit
val exit : landmark -> unit Die register erklärt neue Wahrzeichen und sollte am Toplevel verwendet werden. Mit den Funktionen enter und exit werden verwendet, um den Anteil des an ein Wahrzeichen beigefügten Code -Codes abzugrenzen. Am Ende der Profilerstellung holen wir für jedes Wahrzeichen die aggregierten Zeitinformationen, die für die Ausführung des entsprechenden Code -Stücks ausgeführt wurden. Während der Ausführung wird auch eine Spur jedes besuchten Wahrzeichens erfasst, um einen "Callgraph" zu erstellen.
Zum Beispiel:
open Landmark
let loop = register " loop "
let sleep = register " sleep "
let main = register " main "
let zzz () =
enter sleep;
Unix. sleep 1 ;
exit sleep
let () =
begin
start_profiling () ;
enter main;
enter loop;
for _ = 1 to 9 do
zzz ()
done ;
exit loop;
zzz () ;
exit main;
end (Diese Datei kann mit ocamlfind ocamlc -o prog -package landmarks -package unix -linkpkg prog.ml ) kompiliert werden.
Der induzierte Callgraph ist:
- 100.00% : main
| - 90.00% : loop
| | - 100.00% : sleep
| - 10.00% : sleep
die umschrieben werden können wie:
clock() -Funktion Die Bibliothek bietet eine Bindung an den Hochleistungszyklen-Zähler für Architekturen X86 32 und 64 Bits (beachten Sie, dass Sie die landmarks-noc.cm(x)a Archiv verwenden können, um Ihre eigene Implementierung bereitzustellen). Es wird verwendet, um die Zeit im instrumentierten Code zu messen.
Um das Schreiben von Boilerplate -Code zu vermeiden, können Sie die mit diesem Paket verteilte PPX -Erweiterung verwenden. Es ermöglicht dem Programmierer, Ausdrücke mit Annotation zu instrumentieren und automatisch Funktionen der Top-Ebene zu instrumentieren.
Der Wert expr [@landmark "name"] wird erweitert in
Landmark. enter __generated_landmark_1;
let r =
try expr with e -> Landmark. exit __generated_landmark_1; raise e
in
Landmark. exit __generated_landmark_1;
rund die Erklärung
let __generated_landmark_1 = Landmark. register " name "ist an der obersten Ebene angehängt.
Es sollte darauf hingewiesen werden, dass diese Transformation keine schwanzrekursiven Aufrufe beibehält (und auch eine Verallgemeinerung der Polymorphismus verhindert). Um diese Probleme zu umgehen, wird empfohlen let rec ... in die andere bereitgestellte Erweiterung zu verwenden let ... in
let [ @ landmark] f = bodyWelches wird erweitert in:
let __generated_landmark_2 = Landmark. register " f "
let f = body
let f x1 ... xn =
Landmark. enter __generated_landmark_2;
let r =
try f x1 ... xn with e -> Landmark. exit __generated_landmark_2; raise e
in
Landmark. exit __generated_landmark_2;
r Wenn die Arität n von f erhalten wird, indem die flachen Ereignisse des fun ... -> und function ... -> im body . Bitte beachten Sie, dass bei Verwendung dieser Annotation mit Let-Rec-Bindungen nur Einstiegs-Punkte-Anrufe aufgezeichnet werden. Zum Beispiel im folgenden Code -Stück
let () =
let [ @ landmark] rec even n = (n = 0 ) || odd (n - 1 )
and [ @ landmark] odd n = (n = 1 ) || n > 0 && even (n - 1 )
in Printf. printf " 'six is even' is %b n " (even 6 )Das Wahrzeichen, das mit "sogar" verbunden ist, wird genau einmal (und nicht dreimal!) Überquert, während der Kontrollfluss nicht durch das mit "Odd" verbundene Wahrzeichen verläuft.
Die Strukturanmerkungen [@@@landmark "auto"] und [@@@landmark "auto-off"] aktivieren oder deaktivieren die automatische Instrumentierung von Top-Level-Funktionen in einem Modul. Im automatischen Modus werden alle Funktionen deklariert implizit kommentiert. Die automatische Instrumentierung kann für alle Dateien über Option auto in OCAML_LANDMARKS aktiviert/deaktiviert werden, wie unten aufgeführt.
Die Umgebungsvariable OCAML_LANDMARKS wird in zwei verschiedenen Phasen gelesen: Wenn der PPX -Reschalter ausgeführt wird und wenn das Landmarksmodul von einem instrumentierten Programm geladen wird. Diese Variable wird als von Kommas getrennte Liste der Elemente der option=argument oder option analysiert, wobei option lautet:
Während der PPX -Rewriter -Stufe (zur Zusammenstellung Zeit):
auto (keine Argumente): Schalten Sie die automatische Instrumentierung standardmäßig ein (verhält sich so, als ob jedes Modul mit Annotation beginnt [@@@landmark "auto"] ).
threads (keine Argumente): teilt der PPX -Erweiterung mit, dass sie das Modul Landmark_threads anstelle des Modul Landmark verwenden soll.
Beim Laden eines instrumentierten Programms (zur Laufzeit):
format mit möglichen Argumenten: textual (Standard) oder json . Es steuert das Ausgangsformat der Profilerstellung, das entweder eine konsolenfreundliche Darstellung oder eine JSON -Codierung des Callgraphs ist.
threshold mit einer Zahl zwischen 0,0 und 100,0 als Argument (Standard: 1.0). Wenn der Schwellenwert nicht Null ist, wird die textliche Ausgabe Knoten im Callgraph unterhalb dieser Schwelle (in Prozent der Zeit ihres übergeordneten) ausblenden. Diese Option ist für andere Formate bedeutungslos.
output mit einem möglichen Argument: stderr (Standard), stdout , temporary , <file> (wobei <file> der Pfad einer Datei ist). Es wird angegeben, wo die Ergebnisse der Profilerstellung ausgegeben werden sollen. Bei temporary wird es in einer temporären Datei gedruckt (der Name dieser Datei wird auf dem Standardfehler gedruckt). Sie können auch temporary:<directory> verwenden, um das Verzeichnis anzugeben, in dem die Dateien generiert werden.
debug ohne Argument. Aktiviert einen ausführlichen Modus, der jedes Mal, wenn die Landmarken -Primitiven aufgerufen werden, Spuren auf Stderr ausgibt.
time ohne Argument. Sammeln Sie auch Sys.time -Zeitstempel während der Profilerstellung.
off ohne Argument. Profilerstellung deaktivieren.
on ohne Argument. Profilerstellung aktivieren (Standard; kann weggelassen werden).
allocation ohne Argument. Sammeln Sie auch Gc.allocated_byte -Daten.
Sie können den Web -Viewer entweder auf Ihrem Computer kompilieren oder online durchsuchen. Sie müssen die JSON -Dateien mit dem FilePicker laden und dann klicken, um den Callgraph zu durchsuchen.
Das Landmark ist nicht fadensicher. Wenn Sie mehrere Threads haben, müssen Sie sicherstellen, dass höchstens ein Thread einen instrumentierten Code ausführt. Dazu können Sie das Landmark_threads -Modul (ein Archiv in den Landmarken-Threads.cm (x) ein Archiv verwenden) verwenden, das nicht mit Thread-sichere Funktionen in allen Threads, aber das mit der Profilierung begann, verhindert.
Die Anmerkung der Ausdrücke kann mit dem Polymorphismus eintauchen (dies ist nicht der Fall für die Annotation für die Ablehnung). Beispielsweise wird das folgende Code nicht kompilieren:
let test = ( fun x -> x)[ @ landmark " test " ]
in test " string " , test 1 Dieses "Landmark" -Paket wird von Lexifi gemäß den Bestimmungen der MIT -Lizenz lizenziert.
Kontakt: [email protected]
