Top Description Methods
org.graalvm.nativebridge

public Interface BinaryMarshaller<T>

Known Direct Implementers
org.graalvm.nativebridge.DefaultStackTraceMarshaller, org.graalvm.nativebridge.DefaultThrowableMarshaller, org.graalvm.nativebridge.NullableBinaryMarshaller, org.graalvm.nativebridge.StackTraceElementMarshaller, org.graalvm.nativebridge.StringMarshaller
Imports
java.util.Objects
A marshaller used by the native bridge processor to read or write method parameters and results of a custom type. Marshallers are used to support types that are not directly implemented by the native bridge processor.
See Also
JNIConfig.Builder

Method Summary

Modifier and TypeMethod and Description
public default int
inferSize(T object)

Estimates a size in bytes needed to marshall given object.

public default int
inferUpdateSize(T object)

Estimates a size in bytes needed to marshall Out parameter passed back to caller from a foreign method call.

public static <T> BinaryMarshaller<T>
nullable(BinaryMarshaller<T> forMarshaller)

Decorates forMarshaller by a BinaryMarshaller handling null values.

public T
read(BinaryInput input)

Deserializes and recreates an object passed to a foreign method.

public default void
readUpdate(BinaryInput input, T object)

Deserializes and updates the mutable state of a given object to support Out semantics.

public void
write(BinaryOutput output, T object)

Decomposes and serializes the given object passed to a foreign method.

public default void
writeUpdate(BinaryOutput output, T object)

Decomposes and serializes the mutable state of a given object to support Out semantics.

Method Detail

inferSizeback to summary
public default int inferSize(T object)

Estimates a size in bytes needed to marshall given object. The returned value is used to pre-allocate the BinaryOutput's buffer. The accuracy of the estimate affects the speed of marshalling. If the estimate is too small, the pre-allocated buffer must be re-allocated and the already marshalled data must be copied. Too large a value may cause the static buffer to be unused and the dynamic buffer to be unnecessarily allocated.

inferUpdateSizeback to summary
public default int inferUpdateSize(T object)

Estimates a size in bytes needed to marshall Out parameter passed back to caller from a foreign method call. The accuracy of the estimate affects the speed of marshalling. If the estimate is too small, the pre-allocated buffer must be re-allocated and the already marshalled data must be copied. Too large a value may cause the static buffer to be unused and the dynamic buffer to be unnecessarily allocated. Marshallers that do not support Out parameters do not need to implement this method. The default implementation throws UnsupportedOperationException. To support Out parameters the BinaryMarshaller must implement also writeUpdate(BinaryOutput, Object) and readUpdate(BinaryInput, Object).

See Also
BinaryMarshaller#writeUpdate(BinaryOutput, Object), BinaryMarshaller#readUpdate(BinaryInput, Object)
nullableback to summary
public static <T> BinaryMarshaller<T> nullable(BinaryMarshaller<T> forMarshaller)

Decorates forMarshaller by a BinaryMarshaller handling null values. The returned BinaryMarshaller calls the forMarshaller only non-null values.

readback to summary
public T read(BinaryInput input)

Deserializes and recreates an object passed to a foreign method.

readUpdateback to summary
public default void readUpdate(BinaryInput input, T object)

Deserializes and updates the mutable state of a given object to support Out semantics. Marshallers that do not support Out parameters do not need to implement this method. The default implementation throws UnsupportedOperationException. To support Out parameters the BinaryMarshaller must implement also writeUpdate(BinaryOutput, Object) and inferUpdateSize(Object).

Annotations
@SuppressWarnings:unused
See Also
BinaryMarshaller#writeUpdate(BinaryOutput, Object), BinaryMarshaller#inferUpdateSize(Object)
writeback to summary
public void write(BinaryOutput output, T object)

Decomposes and serializes the given object passed to a foreign method.

writeUpdateback to summary
public default void writeUpdate(BinaryOutput output, T object)

Decomposes and serializes the mutable state of a given object to support Out semantics. Marshallers that do not support Out parameters do not need to implement this method. The default implementation throws UnsupportedOperationException. To support Out parameters the BinaryMarshaller must implement also readUpdate(BinaryInput, Object) and inferUpdateSize(Object).

The Out parameters are passed in the following way:

  1. The start point method writes the parameter using write(BinaryOutput, Object).
  2. A foreign method call is made.
  3. The end point method reads the parameter using read(BinaryInput).
  4. The end point receiver method is called with the unmarshalled parameter.
  5. After calling the receiver method, the end point method writes the mutated Out parameter state using writeUpdate(BinaryOutput, Object).
  6. A foreign method returns.
  7. The state of the Out parameter is updated using readUpdate(BinaryInput, Object).

Annotations
@SuppressWarnings:unused
See Also
BinaryMarshaller#readUpdate(BinaryInput, Object), BinaryMarshaller#inferUpdateSize(Object)