C-Libraries in Java nutzen 3: Komplexe Anwendung, Fallstricke und Best Practices

Javas Foreign Function & Memory API (FFM) dient dazu, auf Code in einer Shared Library beziehungsweise DLL zuzugreifen, der in einer Programmiersprache wie C oder Rust geschrieben ist. Allerdings muss der Code dazu einige Voraussetzungen erfüllen.

Diese dreiteilige Artikelserie zeigt anhand einer in C geschriebenen Demo-Library, wie eine Java-Anwendung die Funktionen der Bibliothek aufruft, welche Vorbereitungen erforderlich sind und welche Regeln zu beachten sind.

Nachdem die ersten beiden Teile die wichtigsten Begriffe und Techniken beim Zugriff von Java auf nativen Code via der FFM-API gezeigt haben, behandelt dieser dritte und letzte Teil einige Spezialitäten, die zu beachten sind.

Segmente mit Slicing zuschneiden

Es gibt Anwendungen, die nicht das vollständige MemorySegment benutzen sollen, sondern nur einen Teil davon – beispielsweise wenn sie eine Liste übergeben bekommen, aber nur Teile davon benötigen. Dann ist es praktisch, wenn man nicht immer auf das komplette Array zugreifen muss, sondern sich eine Art View über den Speicherbereich legen kann – genau das leistet die Methode asSlice. Sie schneidet einen Bereich aus dem Segment aus und liefert ein neues Segment für diesen Bereich.

Wenn etwa ein MemorySegment 64 Byte lang ist, ließen sich folgendermaßen die letzten 16 Byte davon abrufen:

MemorySegment segment = arena.allocate(64);
MemorySegment info = segment.asSlice(48, 16);

segment enthält hier den gesamten Speicherbereich. Die Methode asSlice() schneidet die 16 Bytes ab Position 48 heraus.

Die Daten werden dabei aber nicht kopiert, sondern es entsteht eine View über den ausgewählten Bereich. Wenn sich der Inhalt des Bereichs ändert (im Beispiel der Bereich info), dann ändert sich auch der Originalspeicherbereich segment.

Die Länge des Segments

Ein Problem entsteht, wenn das Segment eine falsche Länge hat – mit reinterpret kann man die Länge des Segmentes neu festlegen. In manchen Fällen kann es vorkommen, dass das Segment mit der Länge 0 zurückgegeben wird, beispielsweise, wenn die native Funktion einen void*-Pointer zurückgibt. Ein Zugriff auf das Segment würde eine ArrayIndexOutOfBoundException auslösen. Daher muss man zunächst das Segment auf die richtige Länge setzen, was voraussetzt, dass sie bekannt ist.

Für folgendes Beispiel liefert die native Funktion getMemory() einen void*-Pointer auf einen Speicherbereich zurück. Außerdem ist bekannt, dass der Speicherbereich 100 Byte groß ist. Dann kann man folgendermaßen auf das Ergebnis zugreifen:

MemorySegment segment = (MemorySegment) method.invoke();
MemorySegment value = segment.reinterpret(100);
String result = value.getString(0);
System.out.println("Result getMemory:" + result);

Typinfos zur Laufzeit

Oft ist unklar, wie viele Byte ein Datentyp in C auf einer bestimmten Plattform belegt. Der folgende Code ruft die Größe des Datentyps auf der verwendeten Plattform ab. Der Code ermittelt alle unterstützten Datentypen und zeigt die benötigte Größe in Bytes und das Alignment für den Datentyp long an:

public void printTypeInfos()
{
  Map typeInfos = linker.canonicalLayouts();
  System.out.println("Canonical layout keys: " + 
                     typeInfos.keySet());
  printTypeInfo(typeInfos, "long");
}

private void printTypeInfo(Map typeInfos, 
                           String type)
{
  MemoryLayout typeLayout = typeInfos.get(type);
  if (typeLayout != null)
  {
    System.out.println("C '" + type + "' layout: " + typeLayout +  
                       ", size=" + typeLayout.byteSize() + ", 
                       align=" + typeLayout.byteAlignment());
  }
  else
  {
    System.out.println("Datentyp“ + type + " nicht in“  +  
    „canonicalLayouts() enthalten");
  }
}	

Plattformunabhängig entwickeln

Wer eine Library auf mehreren Betriebssystemen plattformübergreifend nutzen möchte, sollte zunächst mit einem Betriebssystem beginnen und nach dem erfolgreichen Einsatz prüfen, ob die genutzten Funktionen sich auch unter den anderen Betriebssystemen problemlos verwenden lassen.

Ich musste beispielsweise bei meinem Projekt zum Zugriff auf das Hardware-Sicherheitsmodul (HSM) feststellen, dass die Portabilität zum Teil sehr problematisch ist, da sie von den verfügbaren Treibern und Shared Libraries abhängt. So war ein Zugriff auf ein HSM via opensc unter Linux kein Problem, während sich unter Windows einige Funktionen gar nicht nutzen ließen, sondern eine Access Violation in der JVM hervorriefen.

Falls es deutliche Unterschiede zwischen den Plattformen gibt, ist ein Weg, die Funktionen in einer gemeinsamen Basisklasse zu abstrahieren und dann in abgeleiteten Klassen für jede Plattform unterschiedlich zu gestalten.

Mögliche Probleme beim plattformübergreifenden Zugriff sind

• unterschiedliche Größen der Datentypen,
• unterschiedliche Größen von Strukturen,
• unterschiedliches Alignment der Elemente in einer Struktur.

In diesem Fall ist der Zugriff auf den Sourcecode der Shared Library hilfreich. Sollte er nicht möglich sein, lassen sich bestimmte Informationen über die Größe der Datentypen auf der Zielplattform mithilfe der Methode printTypeInfos() ermitteln.

Best Practices

Während meiner Arbeit mit der Foreign Function & Memory API haben sich einige Best Practices herauskristallisiert. So ist es sinnvoll, zunächst mit einfachen Libraries und einfachen Funktionen anzufangen, bevor man sich an größere Libraries beziehungsweise komplexere Funktionen wagt.

Sinnvoll ist es Throwable abzufangen und in eigene Exceptions umzuwandeln, die von RuntimeException abgeleitet sind.

Wer die gleichen Funktionen aus der Library mehrfach benötigt, sollte Method-Handles in einer Map cachen, um nicht immer wieder dieselben Infos abrufen zu müssen. Strukturen sollte man immer per Adresse (ValueLayout.ADDRESS) übergeben und die Strukturen als eigene Klasse mappen, damit der Code übersichtlich bleibt.

Wenn Anwendungen Speicherbereiche allokieren müssen, sollte die Arena dafür möglichst weit oben in der Hierarchie stehen, und die Anwendung sollte die Arena mit try-with-resources erzeugen, damit die Freigabe des Speichers automatisch erfolgen kann.

Das Tool jextract sollte man besser meiden. Eine manuelle Implementierung ist einfacher zu verstehen und vor allem auch zu warten.

Wer den Sourcecode der Shared Library unter Kontrolle hat, sollte auf Datentypen wie int32_t und int64_t setzen, damit klar ist, wie viel Byte sie jeweils belegen.

Für größere Projekte kann es empfehlenswert sein, einen Basis-Layer für den Zugriff auf die C-Funktionen zu implementieren und in einem weiteren Layer die Zugriffschicht für Java draufzusetzen, die keinerlei FFM-spezifische Details mehr enthalten sollte. Bei sehr umfangreichen Projekten empfiehlt sich eine zusätzliche Komfortschicht, die die wichtigsten Use Cases kapselt.

Checkliste bei Fehlern

Bei der Suche nach Fehlerursachen im Zusammenspiel zwischen Java und C mit der Foreign Function & Memory API helfen ein paar Fragen:

• Ist der richtige Library-Pfad angegeben?
• Ist es die richtige Shared Library (32 Bit oder 64 Bit)?
• Lässt sich die Shared Library überhaupt laden?
• Stimmen die Funktionsnamen?
• Stimmen die Parameter (Anzahl und Datentypen) und der Rückgabewert überein?
• Bei den Datentypen: Stimmen die Größen überein? Insbesondere der Datentyp long in C ist kritisch, da sich die Größe auf verschiedenen Plattformen unterscheidet – in Windows müssen Anwendungen ihn als JAVA_INT behandeln, unter Linux dagegen als ValueLayout.JAVA_LONG.