English ▾ Themen ▾ Neueste Version ▾ gitformat-chunk zuletzt aktualisiert in 2.43.0

NAME

gitformat-chunk - Chunk-basierte Dateiformate

SYNOPSIS

Verwendet von gitformat-commit-graph[5] und dem "MIDX"-Format (siehe die Pack-Format-Dokumentation in gitformat-pack[5]).

BESCHREIBUNG

Einige Dateiformate in Git verwenden ein gemeinsames Konzept von "Chunks", um Abschnitte der Datei zu beschreiben. Dies ermöglicht einen strukturierten Zugriff auf eine große Datei, indem ein kleines "Inhaltsverzeichnis" für die restlichen Daten gescannt wird. Dieses gemeinsame Format wird von den Dateien commit-graph und multi-pack-index verwendet. Sehen Sie sich das multi-pack-index Format in gitformat-pack[5] und das commit-graph Format in gitformat-commit-graph[5] an, um zu erfahren, wie Chunks zur Beschreibung strukturierter Daten verwendet werden.

Ein chunk-basiertes Dateiformat beginnt mit einigen Header-Informationen, die für dieses Format spezifisch sind. Dieser Header sollte genügend Informationen enthalten, um den Dateityp, die Formatversion und die Anzahl der Chunks in der Datei zu identifizieren. Anhand dieser Informationen kann die Datei den Beginn des chunk-basierten Bereichs bestimmen.

Der chunk-basierte Bereich beginnt mit einem Inhaltsverzeichnis, das beschreibt, wo jeder Chunk beginnt und endet. Dies besteht aus (C+1) Zeilen mit jeweils 12 Bytes, wobei C die Anzahl der Chunks ist. Betrachten Sie die folgende Tabelle

| Chunk ID (4 bytes) | Chunk Offset (8 bytes) |
|--------------------|------------------------|
| ID[0]              | OFFSET[0]              |
| ...                | ...                    |
| ID[C]              | OFFSET[C]              |
| 0x0000             | OFFSET[C+1]            |

Jede Zeile besteht aus einer 4-Byte-Chunk-Identifikation (ID) und einem 8-Byte-Offset. Jede Ganzzahl wird in Netzwerk-Byte-Reihenfolge gespeichert.

Die Chunk-Identifikation ID[i] ist eine Bezeichnung für die in dieser Datei gespeicherten Daten von OFFSET[i] (inklusiv) bis OFFSET[i+1] (exklusiv). Somit ist die Größe des iten Chunks gleich der Differenz zwischen OFFSET[i+1] und OFFSET[i]. Dies erfordert, dass die Chunk-Daten zusammenhängend in der gleichen Reihenfolge wie das Inhaltsverzeichnis erscheinen.

Der letzte Eintrag im Inhaltsverzeichnis müssen vier Null-Bytes sein. Dies bestätigt, dass das Inhaltsverzeichnis endet, und liefert den Offset für das Ende der chunk-basierten Daten.

Hinweis: Das chunk-basierte Format erwartet, dass die Datei *mindestens* einen nachfolgenden Hash nach OFFSET[C+1] enthält.

Funktionen für die Arbeit mit chunk-basierten Dateiformaten sind in chunk-format.h deklariert. Die Verwendung dieser Methoden bietet zusätzliche Überprüfungen, die Entwickler beim Erstellen neuer Dateiformate unterstützen.

Schreiben von chunk-basierten Dateiformaten

Um ein chunk-basiertes Dateiformat zu schreiben, erstellen Sie eine struct chunkfile, indem Sie init_chunkfile() aufrufen und einen Zeiger auf struct hashfile übergeben. Der Aufrufer ist verantwortlich für das Öffnen der hashfile und das Schreiben von Header-Informationen, damit das Dateiformat identifizierbar ist, bevor das chunk-basierte Format beginnt.

Rufen Sie dann add_chunk() für jeden Chunk auf, der zum Schreiben vorgesehen ist. Dies füllt die chunkfile mit Informationen über die Reihenfolge und Größe jedes zu schreibenden Chunks. Geben Sie einen Funktionszeiger chunk_write_fn an, um das Schreiben der Chunk-Daten bei Bedarf durchzuführen.

Rufen Sie write_chunkfile() auf, um das Inhaltsverzeichnis in die hashfile und anschließend jeden der Chunks zu schreiben. Dies überprüft, ob jeder Chunk die erwartete Datenmenge geschrieben hat, damit das Inhaltsverzeichnis korrekt ist.

Rufen Sie schließlich free_chunkfile() auf, um die Daten der struct chunkfile zu löschen. Der Aufrufer ist verantwortlich für die Finalisierung der hashfile, indem der nachfolgende Hash geschrieben und die Datei geschlossen wird.

Lesen von chunk-basierten Dateiformaten

Um ein chunk-basiertes Dateiformat zu lesen, muss die Datei als speicherzugeordneter Bereich geöffnet werden. Die Chunk-Format-API erwartet, dass die gesamte Datei als zusammenhängender Speicherbereich zugeordnet ist.

Initialisieren Sie einen Zeiger auf struct chunkfile mit init_chunkfile(NULL).

Nachdem Sie die Header-Informationen vom Anfang der Datei gelesen haben, einschließlich der Chunk-Anzahl, rufen Sie read_table_of_contents() auf, um die struct chunkfile mit der Liste der Chunks, ihren Offsets und ihren Größen zu füllen.

Extrahieren Sie die Dateninformationen für jeden Chunk mit pair_chunk() oder read_chunk()

  • pair_chunk() weist einen gegebenen Zeiger dem Speicherort innerhalb der speicherzugeordneten Datei zu, der dem Offset des Chunks entspricht. Wenn der Chunk nicht existiert, wird der Zeiger nicht geändert.

  • read_chunk() nimmt einen Funktionszeiger chunk_read_fn entgegen und ruft ihn mit den entsprechenden anfänglichen Zeiger- und Größeninformationen auf. Die Funktion wird nicht aufgerufen, wenn der Chunk nicht existiert. Verwenden Sie diese Methode, um Chunks zu lesen, wenn Sie eine sofortige Analyse durchführen müssen oder wenn Sie Logik basierend auf der Größe des Chunks ausführen müssen.

Nachdem Sie diese Methoden aufgerufen haben, rufen Sie free_chunkfile() auf, um die Daten der struct chunkfile zu löschen. Dies schließt den speicherzugeordneten Bereich nicht. Es wird erwartet, dass die Aufrufer diese Daten für den Zeitraum besitzen, in dem die Zeiger in den Bereich benötigt werden.

Beispiele

Diese Dateiformate verwenden die Chunk-Format-API und können als Beispiele für zukünftige Formate dienen

  • commit-graph: siehe write_commit_graph_file() und parse_commit_graph() in commit-graph.c, wie die Chunk-Format-API zum Schreiben und Parsen des Commit-Graph-Dateiformats verwendet wird, das im Commit-Graph-Dateiformat in gitformat-commit-graph[5] dokumentiert ist.

  • multi-pack-index: siehe write_midx_internal() und load_multi_pack_index() in midx.c, wie die Chunk-Format-API zum Schreiben und Parsen des Multi-Pack-Index-Dateiformats verwendet wird, das im Abschnitt Multi-Pack-Index-Dateiformat von gitformat-pack[5] dokumentiert ist.

GIT

Teil der git[1] Suite