Using the Raw Native Interface

Previous

Introduction

Index

Next

Raw Native Interface Enhancements for SDK 2.0 Preview Release

The Raw Native Interface (or RNI) has been extended as a result of feedback and performance enhancements. The enhancements made to RNI are in the following four primary areas:

• Additional API's to enable reflection from native code
• Changes to support future garbage collection performance enhancements
• RNIGetCompatibleVersion requirement for RNI DLLs
• RNI invocation APIs

Reflection APIs

A number of native reflection APIs have been added to improve accessibility of an object's methods and fields. Using these APIs insulates DLLs from changes to the underlying object model or changes in the class hierarchy.

Users of RNI should use the new write barrier support functions to set an object field inside another object. These APIs are GCSetObjectReferenceForObject and GCSetObjectReferenceForHandle. Also, Field_SetValue, already in RevE (the VM version in SDK 1.5), will support the write barrier. RNI developers are encouraged to use the "Field_" reflection APIs added in RevE because these APIs abstract the object layout. Since these APIs are available on RevE, it should be possible to make a single DLL that will work on RevE and Internet Explorer 4.0.

Future Garbage Collection Performance Enhancements

In order to support future garbage collection enhancements, changes have been made to the internal object model to facilitate more effective garbage collection, and enabling future "write-barrier" support in the garbage collector (see Details of the New GC Model below for details). To insulate code from these or future changes to the object model, developers are encouraged to use the reflection APIs described above. A Java object may still be accessed as a "C" structure, but code will need to be recompiled using the updated msjavah tool provided in this SDK.

RNIGetCompatibleVersion Requirement

Due to the object model changes described above, many RNI DLLs designed for earlier versions of the Microsoft virtual machine will need to be recompiled. In order to identify whether or not a RNI DLL is compatible with the current version of the VM, the VM will call the RNI DLL's RNIGetCompatibleVersion export. RNI DLL's that do not export this API will not be loaded by the current VM.

RNI Invocation APIs

The virtual machine supports two new invocation APIs, PrepareThreadForJava and UnprepareThreadForJava, that can be used to execute RNI APIs on any Win32 thread. An invocation sample is provided in this SDK. Documentation beyond this sample will be provided in a future version of this SDK.

Details of the New GC Model

The ordering in which values are laid out within objects has changed.

Previously, if you had a class A with a string, an int and a string, followed by class B with an int and a string, the object layout in memory is as follows:

From A	string (can be GC'd)
	int (atomic non-GC-able)
	string
From B	int
	string

The new GC model reduces the number of GC roots (in this example there are three).

The new object layout coalesces GC-able objects within a class, and alternates object location from beginning to end, to coalesce between classes. The object layout for the above would be as follows:

From A	int (atomic non-GC-able)
	string (can be GC'd)
	string
From B	string
	int

This gives just one GC root in the example, rather than three.

The ramifications of this model change is that all code that uses RNI will need to be rebuilt and recompiled with the new msjavah tool. Existing code that hasn't been recompiled will not run on existing VM's. Also, existing code that relies on accessing strings directly, rather than using a provided API, will break.

For more detailed description of the new and updated API's, see the SDK reference documentation.