com.is2t.hil

Interface NativeInterface

public interface NativeInterface

This class provides some utilities to implement simulated natives.

• It allows to refresh/flush the content of arrays passed as arguments through HIL protocol. Synchronization is done manually to limit byte transfer (speed optimization). An immutable array can be synchronized (refresh/flush) at any time. An array passed as argument is local to the invoke context (new instance). It cannot be refreshed but it may be flushed when the method that has created this argument returns.
• It provides interaction to get back resources content
• It also gives a framework to interact with the shutdown process of the whole simulation thanks to StopListener and the stop() method

Method Summary

Modifier and Type	Method and Description
void	addStopListener(StopListener stopListener) Register a stop listener. The stop listeners will be notified when the simulation stops.
void	flushContent(Object array) Flush fully an array. Equivalent to call flushContent(Object, int, int) with the full array range.
void	flushContent(Object array, int offset, int length) Flush the content of an array. Only range [offset, offset + length - 1] is flushed.
void	flushImmortalContent(Object array) Flush fully an immortal array. Equivalent to call flushImmortalContent(Object, int, int) with the full array range.
void	flushImmortalContent(Object array, int offset, int length) Flush content of an immortal array. Only range [offset, offset + length - 1] is flushed.
int	getCurrentJavaThreadID() Gets the ID of the current Java thread.
byte[]	getResourceContent(String resourceName) Get full content of a resource.
boolean	isImmortal(Object obj) Tells whether an object is an immortal array or not.
void	refreshContent(Object array) Refresh full content of array if it is immortal. Does nothing if the given object is not an immortal array. Equivalent to call refreshImmortalContent(Object) assuming that the array is immortal.
void	refreshContent(Object array, int offset, int length) Refresh content of array if it is immortal. Does nothing if the given object is not an immortal array.
void	refreshImmortalContent(Object array) Refresh fully an immortal array. Equivalent to call refreshImmortalContent(Object, int, int) with the full array range.
void	refreshImmortalContent(Object array, int offset, int length) Refresh content of an immortal array. Only range [offset, offset + length - 1] is refreshed.
void	resumeJavaThread(int javaThreadID) Resume the given Java thread if it is suspended.
void	stop() Allows to request the simulation stop.
boolean	suspendCurrentJavaThread(long timeout) Causes the current Java thread to pause its Java execution after the end of the current native method.
void	toCString(String javaString, byte[] cString) Transforms a Java String into a C String. The platform default encoding is used to transform Java characters into C characters. The created C String is a NULL terminated String (ends with '\0').
String	toJavaString(byte[] cString) Transforms a C String into a Java String, using platform default encoding.

Method Detail

addStopListener

void addStopListener(StopListener stopListener)

Register a stop listener.
The stop listeners will be notified when the simulation stops.

Parameters:

stopListener - the listener to register.

flushContent

void flushContent(Object array)

Flush fully an array.
Equivalent to call flushContent(Object, int, int) with the full array range.

flushContent

void flushContent(Object array,
                  int offset,
                  int length)

Flush the content of an array.
Only range [offset, offset + length - 1] is flushed. If array is immortal, this method calls flushImmortalContent(Object, int, int). Otherwise, if array has been passed as argument of an invoke method, the content of the array is marked to be flushed when method returns. This method may be called many times to extend the range to flush (union of intervals).

Parameters:

array - the immortal array to flush.

offset - the start index of the range.

length - the length of the range.

Throws:

IllegalArgumentException - if the given array is not an array or is not immortal.

ArrayIndexOutOfBoundsException - if the given range is invalid.

BrokenConnection - if the array cannot be flushed.

flushImmortalContent

void flushImmortalContent(Object array)

Flush fully an immortal array.
Equivalent to call flushImmortalContent(Object, int, int) with the full array range.

flushImmortalContent

void flushImmortalContent(Object array,
                          int offset,
                          int length)

Flush content of an immortal array.
Only range [offset, offset + length - 1] is flushed.

Parameters:

array - the immortal array to flush.

offset - the start index of the range.

length - the length of the range.

Throws:

IllegalArgumentException - if the given array is not an array or is not immortal.

ArrayIndexOutOfBoundsException - if the given range is invalid.

BrokenConnection - if the array cannot be flushed.

getCurrentJavaThreadID

int getCurrentJavaThreadID()

Gets the ID of the current Java thread.

Returns:

the ID of the current Java thread.

getResourceContent

byte[] getResourceContent(String resourceName)

Get full content of a resource.

Parameters:

resourceName - as described in Class.getResourceAsStream(String).

Returns:

the content of the resource (byte array) or null if not found.

Throws:

IllegalArgumentException - if the given resource name is not absolute.

BrokenConnection - if the resource could not be retrieved.

isImmortal

boolean isImmortal(Object obj)

Tells whether an object is an immortal array or not.

Parameters:

obj - the object to test.

Returns:

true if the given object is an immortal array, false otherwise.

refreshContent

void refreshContent(Object array)

Refresh full content of array if it is immortal.
Does nothing if the given object is not an immortal array.
Equivalent to call refreshImmortalContent(Object) assuming that the array is immortal.

See Also:

isImmortal(Object)

refreshContent

void refreshContent(Object array,
                    int offset,
                    int length)

Refresh content of array if it is immortal.
Does nothing if the given object is not an immortal array. Equivalent to call refreshImmortalContent(Object, int, int) assuming that the array is immortal.

See Also:

refreshImmortalContent(Object, int, int), isImmortal(Object)

refreshImmortalContent

void refreshImmortalContent(Object array)

Refresh fully an immortal array.
Equivalent to call refreshImmortalContent(Object, int, int) with the full array range.

refreshImmortalContent

void refreshImmortalContent(Object array,
                            int offset,
                            int length)

Refresh content of an immortal array.
Only range [offset, offset + length - 1] is refreshed.

Parameters:

array - the immortal array to refresh.

offset - the start index of the range.

length - the length of the range.

Throws:

IllegalArgumentException - if the given array is not an array or is not immortal.

ArrayIndexOutOfBoundsException - if the given range is invalid.

BrokenConnection - if the array cannot be refreshed.

resumeJavaThread

void resumeJavaThread(int javaThreadID)

Resume the given Java thread if it is suspended. If the Java thread is not paused, this resume stays pending. Next call of suspendCurrentJavaThread(long) will not paused the thread.

Parameters:

javaThreadID - the ID of the Java thread to resume.

Throws:

IllegalArgumentException - if the given Java thread ID is invalid.

See Also:

getCurrentJavaThreadID()

stop

void stop()

Allows to request the simulation stop.

suspendCurrentJavaThread

boolean suspendCurrentJavaThread(long timeout)

Causes the current Java thread to pause its Java execution after the end of the current native method. This function is not blocking. The current Java thread will resume its execution after the reception of an external event or after timeout milliseconds.

If a resume has been done on this thread before calling this function, the thread is not paused.

The result of calling this method several times during the same native execution is unpredictable.

Parameters:

timeout - the duration in milliseconds of the pause. If it is equals to zero, then time is not taken into consideration and the thread simply waits until resumed.

Returns:

true if the current java thread will suspend its execution, false if a resume is pending.

Throws:

IllegalStateException - if the method is not called inside a Java native.

See Also:

resumeJavaThread(int)

toCString

void toCString(String javaString,
               byte[] cString)

Transforms a Java String into a C String.
The platform default encoding is used to transform Java characters into C characters.
The created C String is a NULL terminated String (ends with '\0'). The cString array length must be at least javaString.length()+1.
The content of the given cString array is automatically flushed with the method flushContent(Object, int, int). Only javaString.length() bytes are flushed.

Parameters:

javaString - the Java String

cString - byte array which contains the C String.

Throws:

IllegalArgumentException - if javaString or cString is null

ArrayIndexOutOfBoundsException - if cString is too small to contain the string

toJavaString

String toJavaString(byte[] cString)

Transforms a C String into a Java String, using platform default encoding. The C String must be NULL terminated.
The content of the given cString is automatically refreshed with the method refreshContent(Object).

Parameters:

cString - byte array which contains the C String

Returns:

a new Java String.

Throws:

IllegalArgumentException - if cString is null or its length is < 1

IllegalArgumentException - if cString is not NULL terminated.