org.ObjectLayout

Interface Summary
Interface Description

CtorAndArgsProvider<T>
A functional interface for providing a constructor and arguments given a construction context (index, etc.).

Interface Summary
Interface	Description
CtorAndArgsProvider<T>	A functional interface for providing a constructor and arguments given a construction context (index, etc.).

Class Summary
Class	Description
AbstractPrimitiveArray	A abstract base class for subclassable primitive and reference arrays.
ConstructionContext<T>	The construction context for object instantiated within a StructuredArray
CtorAndArgs<T>	Captures a specific constructor and arguments to be passed to it.
Intrinsic.NO_DECLARED_CLASS	A no-op class used to indicate no value set for the `Intrinsic.elementClass()` element.
IntrinsicObjects	Intrinsic objects (declared with the `@Intrisic` annotation) may have their layout within the containing object instance optimized by JDK implementations, such that access to their content is faster, and avoids certain de-referencing steps.
IntrinsicProcessor	A javac annotation processor for the @Intrinsic annotation.
PrimitiveArrayBuilder<S extends AbstractPrimitiveArray>	A builder used for instantiating a `AbstractPrimitiveArray`<T>
PrimitiveArrayModel<S extends AbstractPrimitiveArray>	A model that describes the structure of a PrimitiveArray
PrimitiveByteArray	A subclassable array of bytes.
PrimitiveCharArray	A subclassable array of chars.
PrimitiveDoubleArray	A subclassable array of doubles.
PrimitiveFloatArray	A subclassable array of floats.
PrimitiveIntArray	A subclassable array of ints.
PrimitiveLongArray	A subclassable array of longs.
PrimitiveShortArray	A subclassable array of shorts.
ReferenceArray<T>	A subclassable array of object references.
StructuredArray<T>	An array of non-replaceable objects.
StructuredArrayBuilder<S extends StructuredArray<T>,T>	A builder used for instantiating a `StructuredArray`<T>
StructuredArrayModel<S extends StructuredArray<T>,T>	A model that describes the structure of a StructuredArray

Annotation Types Summary
Annotation Type Description

Intrinsic
The @Intrisic annotation defines a declared object field to be intrinsic to the class it is declared in.

Annotation Types Summary
Annotation Type	Description
Intrinsic	The `@Intrisic` annotation defines a declared object field to be intrinsic to the class it is declared in.

Package org.ObjectLayout Description

ObjectLayout: An optimised memory layout package.

The ObjectLayout package provides some key data structure classes designed with optimised memory layout in mind. These classes are aimed at matching the natural speed benefits similar data structure constructs enable in most C-style languages, while maintaining an idiomatic Java feel and a natural fit with existing code and libraries.

The package classes provide full functionality on all JVMs (of Java SE 5 or above) at reasonable layouts and execution speeds. However, the classes are carefully designed with semantics that would allow an optimised JVM to implement them with improved memory layout not directly expressible in Java.

The StructuredArray class is a good example of this design pattern. StructuredArray is carefully designed to allow a JVM to store it in memory with a layout similar to an array of structs in C-like languages. When a JVM optimises StructuredArray in such a way, array access benefits from both direct (as opposed to de-referenced) dead-reckoning index access, as well as from fixed memory strides during streaming operations.

The three commonly used C-style container layout forms that ObjectLayout seeks to enable in Java are:

An array of structs: struct foo[];
A struct with a struct inside: struct foo { int a; bar b; int c; };
A struct with an array at the end: struct foo { int len; char[] payload; };

The speed benefits in these three forms of layout derive from two dominant benefits:

1. Dead reckoning: In all three forms, the address of the target data field accessed through the containing object can be directly derived from the containing object reference without a data-dependent load operation (no de-referencing or equivalent operation needed).
2. Streaming: In the case of an array of structs, sequential access through multiple members of the containing array result in predictable striding access in memory, enabling prefetch logic (hardware assisted or otherwise) to compensate for much of the latency involved in cache misses.

The matching ObjectLayout forms

StructuredArray provides an idiomatic Java collection form with speed (and semantics) similar to an "array of structs" form, supporting any constructable java Object as an array member.

@Intrinsic provides an idiomatic Java means for declaring member objects that are intrinsic to the instances of the class they are declared in. @Intrinsic provides a "struct in struct" equivalent relationship between Java objects, exposing the speed and layout benefits similar to the same form in the C family languages.

Sub-classable Primitive and Reference array classes (e.g. PrimitiveLongArray and ReferenceArray) provide an idiomatic Java means of declaring constructs with speed (and semantics) similar to "struct with array at the end". They do so by supporting the subclassing of arrays of the various primitive and reference forms possible in Java. StructuredArray similarly supports this capability (via subclassing) for the equivalent of "struct with array of structs at the end".