Layout runtime interfaces

[Angela Lin]

To kick off a discussion about the runtime underpinnings of layouts, I'm
going to describe some of the external interfaces of our functional
prototype. This represents our attempt to interpret the whiteboard
discussions about Layouts in a more concrete way. In particular, it
illustrates the concepts of Layout stub interfaces, generated accessors,
and Locations.

We've made a lot of assumptions about the design based on both our internal
and external discussions.  Do these assumptions reflect your current
thinking as well?

In earlier discussions, there was interest in providing both immutable and
mutable versions of each layout. In our local discussions, we leaned
towards keeping mutability out of the type system and using the object
state (isMutable style flags) to determine if a set operation should be
permitted.  In this approach, the mutability can be left to the programmer.

Given our experience with PackedObjects, we're keen to be able to allow
Layouts to modify both on- and off-heap memory.  A Layout backed by a byte
array (or other on-heap structure) should work just as well as native
memory.

One detail that still needs discussion is whether / how to allow Layouts to
access structured on-heap memory that contains Object references.  There
may be dragons lurking here, but we've seen a lot of interest in this piece
with Packed.

Class Hierarchy
        com.ibm.layout.Location - Encapsulates the memory range to be
accessed using a layout, and security checks (TBD) associated with it

        com.ibm.layout.LayoutType
            com.ibm.layout.Layout  - singleton layout
            com.ibm.layout.Array1D<T>  - 1D array layout
            com.ibm.layout.Array2D<T>  - 2D array layout

Layout, Array1D<T>, Array2D<T> are templates that provide APIs for data
access patterns. The JDK would provide a tool that takes a layout
descriptor as input, and generates a Java interface that extends one of
these templates. I'll call the generated interface a "Layout stub
interface", or just "stub interface". The stub interface must be generated
before a layout can be used by a Java application.

The stub interface defines methods for accessing fields of the structured
data by name. Our prototype allows users to extend the stub interface to
add their own behaviour.

In the context of interfacing Java with native libraries, layout
descriptors would be metadata associated with native library binaries.

            com.ibm.layout.ByteArray1D  - examples of primitive array
layouts, which would be obsoleted by Valhalla support for generics over
primitives
            com.ibm.layout.LongArray1D
            com.ibm.layout.LongArray2D

Annotation Type Hierarchy
    com.ibm.layout.LayoutDesc - Annotation for attaching a layout
descriptor to a stub interface; We've obsoleted this idea, but the
prototype hasn't yet been updated to reflect this. I've left in this
reference because it was an interesting idea.

Usage

// "Point" is a stub interface, generated from a layout descriptor.
// getLayout() invokes a bytecode generator that implements the interface,
using info from the layout descriptor. The implementation is the "accessor
class", which implements access to named fields of the layout.
// The Point instance is only an accessor. It is not inherently attached to
a particular data location.
Point p = Point.getLayout(Point.class);

// Allocate some memory (actual API TBD)
Location loc = new Location(new byte[(int)p.sizeof()]);

// Attach the Point accessor to the memory
p.bindLocation(loc);

// Modify the memory
p.x(10);
p.y(20);


For more specific API ideas, I have attached javadoc extracted from our
prototype. It's very much a work-in-progress, so there are some obvious
omissions and problems:
- no security model
- we haven't properly hidden private data
- was based on Java 7, so used abstract classes instead of interfaces so
that we could provide default method implementations. We happened to use
abstract classes for expediency; we aren't trying to dictate the choice of
one over the other.

Also note that the prototype predates the latest revision of the LDL.

- Angela

(See attached file: PanamaLayoutPrototypeV1.zip)