<!DOCTYPE html><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body><div style="font-family: sans-serif;"><div class="markdown" style="white-space: normal;">
<p dir="auto">In this message Brian wrote out the major features<br>
of an emerging design for value classes:</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">From: Brian Goetz <a href="mailto:brian.goetz@oracle.com" style="color: #777777;">brian.goetz@oracle.com</a><br>
To: … <a href="mailto:valhalla-spec-experts@openjdk.java.net" style="color: #777777;">valhalla-spec-experts@openjdk.java.net</a><br>
Subject: Re: User model stacking: current status<br>
Date: Thu, 23 Jun 2022 15:01:24 -0400</p>
</blockquote>
<p dir="auto">I think controlling the complexity by having a separate<br>
nested declaration of the value companion type will<br>
work very well.</p>
<p dir="auto">So what exactly does a private value companion do?<br>
What is it you can and cannot do with this type?<br>
What problems are prevented by privatizing it?<br>
How and when is privatization enforced?<br>
What other problems are created by those new rules?</p>
<p dir="auto">I have been pulling on this thread for a few days<br>
now, and I think I have some answers.</p>
<p dir="auto"><a href="http://cr.openjdk.java.net/~jrose/values/encapsulating-val.md" style="color: #3983C4;">http://cr.openjdk.java.net/~jrose/values/encapsulating-val.md</a><br>
<a href="http://cr.openjdk.java.net/~jrose/values/encapsulating-val.html" style="color: #3983C4;">http://cr.openjdk.java.net/~jrose/values/encapsulating-val.html</a></p>
<p dir="auto">(The Hitchhiker’s Guide suddenly comes to mind. Don’t panic!)</p>
<p dir="auto">I expect I will be editing these files as we go.<br>
For reference here is a verbatim copy of the MD file<br>
as it stands right now (minus the header):</p>
<h2 style="font-size: 1.2em;">Background</h2>
<p dir="auto"><em>(We will start with background information. The <strong><a href="#privatization-to-the-rescue" style="color: #3983C4;">new stuff comes<br>
afterward</a></strong>. Impatient readers can find a very quick <strong><a href="#summary-of-restrictions" style="color: #3983C4;">summary of<br>
restrictions</a></strong> at the end.)</em></p>
<h3 style="font-size: 1.1em;">Affordances of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code></h3>
<p dir="auto">Every class or interface <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> comes with a companion type, the<br>
reference type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> derived from <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> which describes any variable<br>
(argument, return value, array element, etc.) whose values are either<br>
null or of a concrete class derived from <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>. We are not in the habit<br>
of distinguishing <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> from <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>, but the distinction is there. For<br>
example, if we call <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object::getClass</code> on a variable of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code><br>
we might not get <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.class</code>; we might even get a null pointer<br>
exception!</p>
<p dir="auto">We are so very used to working with reference types (for short,<br>
<em>ref-types</em>) that we sometimes forget all that they do for us<br>
in addition to their linkage to specific classes:</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> gives a starting point for accessing <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s members.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> provides abstraction: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> or a subtype might not be loaded yet.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> provides the standard uninitialized value <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">null</code>.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> can link <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> objects into graphs, even circular ones.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> has a known size, one "machine word", carefully tuned by the JVM.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> allows a single large object to be shared from many locations.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> with an identity class can centralize access to mutable state.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> values uniformly convert to and from general types like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object</code>.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> variable types can be reflected using <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class</code> mirror objects.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> is safe for publication if the fields of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> are <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">final</code>.</li>
</ul>
<p dir="auto">When I store a bunch of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> objects into an object array or list, sort<br>
it, and then share it with another thread, I am using several of the<br>
above properties; if the other thread down-casts the items to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code><br>
and works on them it relies on those properties.</p>
<p dir="auto">If I implement <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> as a doubly-linked list data structure or a<br>
(alternatively) a value-based class with tree structure, I am using<br>
yet more of the above properties of references.</p>
<p dir="auto">If my <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> object has a lot of state and I pass out many pointers to<br>
it, and perhaps compute and cache interesting values in its mutable<br>
fields, I am again relying on the special properties of references,<br>
as well as of identity classes (if fields are mutable).</p>
<p dir="auto">By the way, in the JVM, variables of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> (some of them at<br>
least) are associated not with <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> simple, but with the so-called<br>
<em>L-descriptor</em> spelled <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">LC;</code>. When we talk about <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> we are<br>
usually talking about those L-descriptors in the JVM, as well.</p>
<p dir="auto">I don't need to think much about this portfolio of properties as I go<br>
about my work. But if they were to somehow fail, I would notice bugs<br>
in my code sooner or later.</p>
<p dir="auto">One of the big consequences of this overall design is that I can write<br>
a class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> which has full control over its instance states. If it is<br>
mutable, I can make its fields private and ensure that mutations occur<br>
only under appropriate locking conditions. Or if I declare it as a<br>
value-based class, I can ensure that its constructor only allows<br>
legitimate instances to be constructed. Under those conditions, I<br>
know that every single instance of my class will have been examined<br>
and accepted by the class constructor, and/or whatever factory and<br>
mutator methods I have created for it. If I did my job right, not<br>
even a race condition can create an invalid state in one of my<br>
objects.</p>
<p dir="auto">Any instance state of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> which has been reached without being<br>
produced from a constructor, factory, mutator, or constant of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> can<br>
be called <em>non-constructed</em>. Of course, inside a class any state<br>
whatever can be constructed, subject to the types of fields and so on.<br>
But the author of the class gets to decide which states are<br>
legitimate, and the decisions are enforced by access control at the<br>
boundaries of the encapsulation.</p>
<p dir="auto">So if I code my class right, using access control to keep bad states<br>
away from my clients, my class's external API will have no<br>
non-constructed states.</p>
<h3 style="font-size: 1.1em;">Costs of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code></h3>
<p dir="auto">In that case why have value types at all, if references are so<br>
powerful? The answer is that reference-based abstraction pays for its<br>
benefits with particular costs, costs that Java programmers do not<br>
always wish to pay:</p>
<ul>
<li>A reference (usually) requires storage for a pointer to the object.</li>
<li>A reference (usually) requires storage for a header embedded inside the object.</li>
<li>Access to an object's fields (usually) requires extra cycles to chase the pointer.</li>
<li>The GC expends effort administering a singular "home location" for every object.</li>
<li>Cache line invalidation near that home location can cause useless memory traffic.</li>
<li>A reference must be able to represent <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">null</code>; tightly-packed types like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">int</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">long</code> would need to add an extra bit somewhere to cover this.</li>
</ul>
<p dir="auto">The major alternative to references, as provided by Valhalla, is flat<br>
objects, where object fields are laid out immediately in their<br>
containers, in place of a pointer which points to them stored<br>
elsewhere. Neither alternative is always better than the other, which<br>
is why Java has both <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">int</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Integer</code> types and their arrays, and<br>
why Valhalla will offer a corresponding choice for value classes.</p>
<h3 style="font-size: 1.1em;">Alternative affordances of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code></h3>
<p dir="auto">Now, instances of a value class can be laid out flat in their<br>
containing variables. But they can also be "boxed" in the heap, for<br>
classic reference-based access. Therefore, a value class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> has not<br>
one but <em>two</em> companion types associated it, not only the reference<br>
companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> but also the value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. Only value<br>
classes have value companions, naturally. The companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is<br>
called a value type (or <em>val-type</em> for short), by contrast with any<br>
reference type, whether <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object.ref</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>.</p>
<p dir="auto">The two companion types are closely related and perform some of the<br>
same jobs:</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> both give a starting point for accessing <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s members.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> can link <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> objects into acyclic graphs.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> values uniformly convert to and from general types like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object</code>.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> variable types can be reflected using <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class</code> mirror objects.</li>
</ul>
<p dir="auto">For these jobs, it usually doesn't matter which type companion does<br>
the work.</p>
<p dir="auto">Despite the similarities, many properties of a value companion type<br>
are subtly different from any reference type:</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is non-abstract: You must load its class file before making a variable.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> cannot nest except by reference; <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> cannot declare a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> field.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> does not represent the value <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">null</code>.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is routinely flattenable, avoiding headers and indirection pointers</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> has configurable size, depending on <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s non-static fields.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> heap variables (fields, array elements) are initialized to all-zeroes.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> might not be safe for publication (even though its fields are <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">final</code>).</li>
</ul>
<p dir="auto">The JVM distinguishes <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> by giving it a different descriptor, a<br>
so-called <em>Q-descriptor</em> of the form <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">QC;</code>, and it also provides a<br>
so-called <em>secondary mirror</em> <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code> which is similar to the<br>
built-in primitive mirrors like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">int.class</code>.</p>
<p dir="auto">As the Valhalla performance model notes, flattening may be expected<br>
but is not fully guaranteed. A <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> stored in an <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object</code><br>
container is likely to be boxed on the heap, for example. But <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code><br>
objects created as bytecode temporaries, arguments, and return values<br>
are likely to be flattened into machine registers, and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> fields<br>
and array elements (at least below certain size thresholds) are also<br>
likely to be flattened into heap words.</p>
<p dir="auto">As a special feature, <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> is potentially flattenable if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is a<br>
value class. There are additional terms and conditions for flattening<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>, however. If <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is not yet loaded, nothing can be done:<br>
Remember that reference types have full abstraction as one of their<br>
powers, and this means building data structures that can refer to them<br>
even before they are loaded. But a class file can request that the JVM<br>
"peek" at a class to see if it is a value class, and if this request<br>
is acted on early enough (at the JVM's discretion), then the JVM can<br>
choose to lay out some or all <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> values as flattened <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code><br>
values <em>plus</em> a boolean or other sentinel value which indicates the<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">null</code> state.</p>
<h3 style="font-size: 1.1em;">Pitfalls of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code></h3>
<p dir="auto">The advantages of value companion types imply some complementary<br>
disadvantages. Hopefully they are rarely significant, but they<br>
must sometimes be confronted.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> might need to load a class file which is somehow unloadable</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> will fail to load if its instance layout directly <em>or indirectly</em> includes a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> field <em>or subfield</em></li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> will throw an exception if you try to assign a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">null</code> to it.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> may have surprising costs for multi-word footprint and assignment (and so might <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> if that is flattened)</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is initialized to its all-zero value, which might be non-constructed</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> might allow data races on its components, creating values which are non-constructed</li>
</ul>
<p dir="auto">The footprint issue shows up most strongly if you have many copies of<br>
the same <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> value; each copy will duplicate all the fields, as<br>
opposed many copies of the same <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> reference, which are likely to<br>
all point to a single heap location with one copie of all the fields.</p>
<p dir="auto">Flat value size can also affect methods like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays.sort</code>, which<br>
perform many assignments of the base type, and must move all fields on<br>
each assignment. If a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> array has many words per element, then<br>
the costs of moving those words around may dominate a sort request.<br>
For array sorting there are ways to reduce such costs transparently,<br>
but it is still a "law of physics" that editing a whole data structure<br>
will have costs proportional to the size of the edited portions of the<br>
data structure, and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> arrays will often be somewhat more compact<br>
than <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> arrays. Programmers and library authors will have to use<br>
their heads when deciding between the new alternatives given by value<br>
classes.</p>
<p dir="auto">But the last two pitfalls are hardest to deal with, because they both<br>
have to do with non-constructed states. These states are the all-zero<br>
state with the second-to-last pitfall, and (with the last pitfall) the<br>
state obtained by mixing two previous states by means of a pair of<br>
racing writes to the same mutable <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> variable in the heap.<br>
Unlike reference types, value types can be manipulated to create these<br>
non-constructed states even in well-designed classes.</p>
<p dir="auto">Now, it may be that a constructor (or factory) might be perfectly able<br>
to create one of the above non-constructed states as well, no strings<br>
attached. In that case, the class author is enforcing few or no<br>
invariants on the states of the value class. Many numeric classes,<br>
like complex numbers, are like this: Initialization to all-zeroes is<br>
no problem, and races between components are acceptable, compared to<br>
the costs of excluding races.</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">(The reader may recall that early JVMs accepted races on the high</p>
</blockquote>
<p dir="auto">and low halves of 64-bit integers as well; this is no longer a<br>
widespread issue, but bigger value types like complex raise the same<br>
issue again, and we need to provide class authors the same solution,<br>
if it fits their class.)</p>
<p dir="auto">There are also some classes for which there are no good defaults, or<br>
for which a good default is definitely not the all-zero bit pattern.<br>
Authors of such types will often wish to make that bit pattern<br>
inaccessible to their clients and provide some factory or constant<br>
that gives the real default. We expect that such types will choose<br>
the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> companion, and rely on the extra null checks to ensure<br>
correct initialization.</p>
<p dir="auto">Other classes may need to avoid other non-constructed values that may<br>
arise from data races, perhaps for reasons of reliability or security.<br>
This is a subtle trade-off; very few class authors begin by asking<br>
themselves about the consequences of data races on mutable members,<br>
and even fewer will ask about <em>races on whole instances</em> of value<br>
types, especially given that fields in value types are always<br>
immutable. For this reason, we will set safety as the default, so<br>
that a class (like complex numbers) which is willing to tolerate data<br>
races must declare its tolerance explicitly. Only then will the JVM<br>
drop the internal costs of race exclusion.</p>
<p dir="auto">Whether to tolerate the all-zero bit pattern is a simpler decision.<br>
Still, it turns out to be useful to give a common single point of<br>
declarative control to handle <em>all</em> non-constructed states, both<br>
the default value of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> and its mysterious data races.</p>
<h2 style="font-size: 1.2em;">Privatization to the rescue</h2>
<p dir="auto"><em>(Here are the important details about the encapsulation of value<br>
types. The impatient reader may enjoy the very quick <strong><a href="#summary-of-restrictions" style="color: #3983C4;">summary of<br>
restrictions</a></strong> at the end of this document.)</em></p>
<p dir="auto">In order to hide non-constructed states, the value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code><br>
may be <em>privatized</em> by the author of the class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>. A privatized<br>
value companion is effectively withdrawn from clients and kept private<br>
to its own class (and to nestmates). Inside the class, the value<br>
companion can be used freely, fully under control of the class author.</p>
<p dir="auto">But untrusted clients are prevented from building uninitialized fields<br>
or arrays of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. This prevents such clients from creating<br>
(either accidentally or purposefully) non-constructed values of type<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. How privatization is declared and enforced is discussed in<br>
the rest of this document.</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">(To review, for those who skipped ahead, non-constructed values are</p>
</blockquote>
<p dir="auto">those not created under control of the class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> by constructors or<br>
other accessible API points. A non-constructed value may be either an<br>
uninitialized variable of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, or the result of a data race on a<br>
shared mutable variable of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. The class itself can work<br>
internally with such values all day long, but we exclude external<br>
access to them by default.)</p>
<h3 style="font-size: 1.1em;">Atomicity as well</h3>
<p dir="auto">As a second tactic, a value class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> may select whether or not the<br>
JVM enforces atomicity of all occurrences of its value companion<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. A non-atomic value companion is subject to data races, and<br>
if it is not privatized, external code may misuse <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> variables<br>
(in arrays or mutable fields) to create non-constructed values via<br>
data races.</p>
<p dir="auto">A value companion which is atomic is not subject to data races. This<br>
will be the default if the the class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> does not explicitly request<br>
non-atomicity. This gives safety by default and limits<br>
non-constructed states to only the all-zero initial value. The<br>
techniques to support this are similar to the techniques for<br>
implementing non-tearing of variables which are declared <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">volatile</code>;<br>
it is as if every variable of an atomic value variable has some (not<br>
all) of the costs of volatility.</p>
<p dir="auto">The JVM is likely to flatten such an atomic value only up to the<br>
largest available atomically settable memory unit, usually 128 bits.<br>
Values larger than that are likely to be boxed, or perhaps treated<br>
with some other expensive transactional technique. Containers that<br>
are immutable can still be fully flattened, since they are not subject<br>
to data races.</p>
<p dir="auto">The behavior of an atomic <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is aligned with that of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>. A<br>
reference to a value class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> <em>never</em> admits data races on <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s<br>
fields. The reason for this is simple: A <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> value is a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code><br>
instance boxed on the heap in a single immutable box-class field of<br>
type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. (Actually, the JVM may partially or wholly flatten the<br>
representation of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> if it can get away with it; full flattening<br>
is likely for JVM locals and stack values, but any such secret<br>
flattening is undetectable by the user.) Since it is <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">final</code> all the<br>
way down (to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s fields) any <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code> value is safely published<br>
without any possibility of data races. Therefore, an extra<br>
declaration of non-atomicity in <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> affects only the value companion<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>.</p>
<p dir="auto">It seems that there are use cases which justify all four combinations<br>
of both choices (privatization and declared non-atomicity), although<br>
it is natural to try to boil down the size of the matrix.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> private & atomic is the default, and safest configuration</li>
</ul>
<p dir="auto">hiding all non-constructed values outside of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> and all data races<br>
even inside of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>. There are some runtime costs.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> public & non-atomic is the opposite, with fewer runtime</li>
</ul>
<p dir="auto">costs. It must be explicitly declared. It is desirable for<br>
numerics like complex numbers, where all possible bitwise states are<br>
meaningful. It is analogous to the situation of a naturally<br>
non-atomic primitive like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">long</code>.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> public & atomic allows everybody to see the all-zero</li>
</ul>
<p dir="auto">initial value but no other non-constructed states. This is<br>
analogous to the situation of a naturally atomic primitive like<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">int</code>.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> private & non-atomic allows <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> complete control over the</li>
</ul>
<p dir="auto">visibility of non-constructed states, but <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> also has the ability<br>
to work internally on arrays of non-atomic elements. <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> should<br>
take care not to leak internally-created flat arrays to untrusted<br>
clients, lest they use data races to hammer non-constructed values<br>
into those arrays.</p>
<p dir="auto">It is logically possible, but there does not seem to be a need, for<br>
allowing a single class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> to work with both kinds of arrays, atomic<br>
and non-atomic. (In principle, the dynamic typing of Java arrays<br>
would support this, as long as each array was configured at its<br>
creation.) The effect of this can be simulated by wrapping a<br>
non-atomic class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> in another wrapper class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">WC</code> which is atomic.<br>
Then <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> arrays are non-atomic and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">WC.val[]</code> arrays are atomic,<br>
yet each kind of array can have the same "payload", a repeated<br>
sequence of the fields of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>.</p>
<h2 style="font-size: 1.2em;">Privatization in code</h2>
<p dir="auto">For source code and bytecode, privatization is enforced by performing<br>
access checks on names.</p>
<h3 style="font-size: 1.1em;">Privatization rules in the language</h3>
<p dir="auto">We will stipulate that a value class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> <em>always</em> has a value<br>
companion type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, even if it is never declared or used. And we<br>
give the author of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> some control over how clients may use the type<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, in a manner roughly similar to nested member classes like<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.M</code>.</p>
<p dir="auto">Specifically, the declaration of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> always selects an access mode for<br>
its value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> from one of the following three choices:</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared private</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared public</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared, but neither public nor private</li>
</ul>
<p dir="auto">If <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared private, then only nestmates of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> may access<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. If it is neither public nor private, only classes in the<br>
same runtime package as <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> may access it. If it is declared public,<br>
then any class that can access <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> may also access <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>.</p>
<p dir="auto">As an independent choice, the declaration of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C may select an atomicity for its value companion </code>C.val` from one of the following two choices:</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is explicitly declared non-atomic</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is not explicitly declared non-atomic, and is thus atomic</li>
</ul>
<p dir="auto">If there is no explicit access declaration for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> in the code of<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>, then <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared private and atomic. That is, we set the<br>
default to the safest and most restrictive choice.</p>
<p dir="auto">In source code, these declarations are applied to explicit occurrences<br>
of the type name <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. The access modification of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is also<br>
transferred to the implicitly declared name <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code></p>
<p dir="auto">The syntax looks like this:</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">class C {
//only one of the following lines may be specified
//the first line is the default
private value companion C.val; //nestmates only
value companion C.val; //package-mates only
public value companion C.val; //all may access
// the non-atomic modifier may be present:
private non-atomic value companion C.val;
public non-atomic value companion C.val;
non-atomic value companion C.val;
}
</code></pre>
<p dir="auto">When a type name <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> or an expression <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> is<br>
used by a class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">X</code>, there are two access checks that occur. First,<br>
access from <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">X</code> to the class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is checked according to the usual<br>
rules of Java. If access to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is permitted, a second check is done<br>
if the companion is not declared <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">public</code>. If the companion is<br>
declared <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">private</code>, then <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">X</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> must be nestmates, or else access<br>
will fail. If the companion is neither <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">public</code> nor <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">private</code>, then<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">X</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> must be in the same package, or else access will fail.</p>
<h3 style="font-size: 1.1em;">Example privatized value companion</h3>
<p dir="auto">Here is an example of a class which refuses to construct its default<br>
value, and which prevents clients from seeing that state:</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">class C {
int neverzero;
public C(int x) {
if (x == 0) throw new IllegalArgumentException();
neverzero = x;
}
public void print() { System.out.println(this); }
private value companion C.val; //privatized (also the default)
// some valid uses of C.val follow:
public C.val[] flatArray() { return new C.val[]{ this }; }
private static C.ref nonConstructedZero() {
return (new C.val[1])[0]; //OK: C.val private but available
}
public static C.ref box(C.val val) { return val; } //OK param type
public C.val unbox() { return this; } //OK return type
// valid use of private C.default, with Lookup negotiation
public static
C.ref defaultValue(java.lang.reflect.MethodHandles.Lookup lookup) {
if (!lookup.in(C.class).hasFullPrivilegeAccess())
return null; //…or throw
return C.default; //OK: default for me and maybe also for thee
}
}
// non-nestmate client:
class D {
static void passByValue(C x) {
C.ref ref = box(x); //OK, although x is null-checked
if (false) box((C.ref) null); //would throw NPE
assert ref == x;
}
static Object useValue(C x) {
x.unbox().print(); //OK, invoke method on C.val expression
var xv = x.unbox(); //OK, although C.val is non-denotable
xv.print(); //OK
//> C.val xv = x.unbox(); //ERROR: C.val is private
return xv; //OK, originally from legitimate method of C
}
static Object arrays(C x) {
var a = x.flatArray();
//> C.val[] va = a; //ERROR: C.val is private
Arrays.toString(a); //OK
C.ref[] a2 = a; //covariant array assignment
C.ref[] na = new C.ref[1];
//> na = new C.val[1]; //ERROR: C.val is private
return a[0]; //constructed values only
}
}
</code></pre>
<p dir="auto">The above code shows how a privatized value companion can and cannot<br>
be used. The type name may never be mentioned. Apart from that<br>
restriction, client code can work with the value companion type as it<br>
appears in parameters, return values, local variables, and array<br>
elements. In this, a privatized companion behaves like other<br>
non-denotable types in Java.</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto"><strong>Rationale:</strong> Note that a companion type is <em>not</em> a real class.</p>
</blockquote>
<p dir="auto">Therefore it cannot appeal, precisely, to the existing provisions (in<br>
JLS or JVMS) for enforcing class accessibility. But because it is a<br>
type, and today <em>nearly all types are classes</em> (and interfaces), users<br>
have a right to expect that encapsulation of companion types will<br>
"feel like" encapsulation of type names. More precisely, users will<br>
hope to re-use their knowledge about how type name access works when<br>
reasoning about companion types. We aim to accommodate that hope. If<br>
it works, users won't have to think very often about the class-vs-type<br>
distinction. That is why the above design emulates pre-existing<br>
usage patterns for non-denotable types.</p>
<h3 style="font-size: 1.1em;">Privatization in translation</h3>
<p dir="auto">When a value class is compiled to a class file, some metadata is<br>
included to record the explicit declaration or implicit status of the<br>
value companion.</p>
<p dir="auto">The access selection of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s value companion (public, package,<br>
private) is encoded in the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">value_flags</code> field of the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ValueClass</code><br>
attribute of the class information in the class file of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>.</p>
<p dir="auto">The <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">value_flags</code> field (16 bits) has the following legitimate values:</p>
<ul>
<li>zero: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> default access, non-atomic</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_PUBLIC</code>: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> public access, non-atomic</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_PRIVATE</code>: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> private access, non-atomic</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_VOLATILE</code>: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> default access, atomic</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_VOLATILE|ACC_PUBLIC</code>: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> public access, atomic</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_VOLATILE|ACC_PRIVATE</code>: <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> private access, atomic</li>
</ul>
<p dir="auto">Other values are rejected when the class file is loaded.</p>
<p dir="auto">(<strong>JVM ISSUE #0:</strong> Can we kill the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_VALUE</code> modifier bit? Do we<br>
really care that <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">jlr.Modifiers</code> kind-of wants to own the reflection<br>
of the contextual modifier <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">value</code>? Who are the customers of this<br>
modifier bit, as a bit? John doesn't care about it personally, and<br>
thinks that if we are going to have an attribute we can get rid of the<br>
flag bit. One implementation issue with killing <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ACC_VALUE</code> is that<br>
class modifiers are processed very late during class loading, while<br>
class modifiers are processed very early. It may be easier to do some<br>
kinds of structural checks on the fly during class loading even before<br>
class attributes are processed. Yet this also seems like a poor<br>
reason to use a modifier bit.)</p>
<p dir="auto">(<strong>JVM ISSUE #1:</strong> What if the attribute is missing; do we reject the<br>
class file or do we infer <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">value_flags=ACC_PRIVATE|ACC_VOLATILE</code>?<br>
Let's just reject the file.)</p>
<p dir="auto">(<strong>JVM ISSUE #2:</strong> Is this <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ValueClass</code> attribute really a good place<br>
to store the "atomic" bit as well? This attribute is a green-field<br>
for VM design, as opposed to the brown-field of modifier bits. The<br>
above language assumes the atomic bit belongs in there as well.)</p>
<p dir="auto">A use of a value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, in any source file, is generally<br>
translated to a use of a Q-descriptor <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">QC;</code>:</p>
<ul>
<li>a field declaration of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> translates to a field-info with a Q-descriptor</li>
<li>a method or constructor declaration that mentions <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> mentions a corresponding Q-descriptor in its method descriptor</li>
<li>a use of a field resolves a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Fieldref</code> with a Q-descriptor component</li>
<li>a use of a method or constructor uses a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Methodref</code> (or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_InterfaceMethodref</code>) with a Q-descriptor component</li>
<li>a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> entry main contain a Q-descriptor or an array type whose element type is a Q-descriptor</li>
<li>a verifier type record may refer to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> which contains a Q-descriptor</li>
</ul>
<p dir="auto">Privatization is enforced for these uses only as much as is needed to<br>
ensure that classes cannot create unintiialized values, fields, and<br>
arrays.</p>
<p dir="auto">If an access from bytecode to a privatized Q-descriptor fails, an<br>
exception is thrown; its type is <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">IllegalAccessError</code>, a subtype of<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">IncompatibleClassChangeError</code>. Generally speaking such an exception<br>
diagnoses an attempt by bytecode to make an access that would have<br>
been prevented by the static compiler, if the Java source program had<br>
been compiled together as a whole.</p>
<p dir="auto">When a field of Q-descriptor type is declared in a class file, the<br>
descriptor is resolved early, before the class is linked, and that<br>
resolution includes an access check which will fail unless the class<br>
being loaded has access to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, as determined by loading <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> and<br>
inspecting its <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ValueClass</code> attribute. These checks prevent untrusted<br>
clients of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> from created non-constructed zero values, in any of<br>
their fields.</p>
<p dir="auto">The timing of these checks, on fields, is aligned with the internal<br>
logic of the JVM which consults the class file of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> to answer other<br>
related questions about field types: (a) whether <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is in fact a<br>
value class, and (b) what is the layout of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, in case the JVM<br>
wishes to flatten the value in a containing field. The third check<br>
(c) is <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> companion accessible happens at the same time. This is<br>
early during class loading for non-static fields, and during<br>
class preparation for static fields.</p>
<p dir="auto">Privatization is <em>not enforced</em> for non-field Q-descriptors, that<br>
occur in method and constructor signatures, and in state descriptions<br>
for the verifier. This is because mere use of Q-descriptors to<br>
describe pre-existing values cannot (by itself) expose non-constructed<br>
values, when those values are on stack or in locals.</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">This can happen invisible at the source-code level as well. An API</p>
</blockquote>
<p dir="auto">might be designed to return values of a privatized type from its<br>
methods or fields, and/or accept values of a privatized type into its<br>
methods, constructors, or fields. In general, the bytecode for a<br>
client of such an API will work with a mix of Q-descriptor and<br>
L-descriptor values.</p>
<p dir="auto">The verifier's type system uses field descriptor types, and thus can<br>
"see" both Q-descriptors and L-descriptors. Clients of a class with a<br>
privatized companion are likely to work mostly with L-descriptor<br>
values but may also have Q-descriptor values in locals and on stack.</p>
<p dir="auto">When feeding an L-descriptor value to an API point that accepts a<br>
Q-descriptor, the verifier needs help to keep the types straight. In<br>
such cases, the bytecode compiler issues <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">checkcast</code> instructions to<br>
adjust types to keep the verifier happy, and in this case the operand<br>
of the checkcast would be of the form <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class["QC;"]</code>.</p>
<p dir="auto">(<strong>JVM ISSUE #3:</strong> The Q/L distinction in the verifier helps the<br>
interpreter avoid extra dynamic null checks around <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">putfield</code>,<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">putstatic</code>, and the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">invoke</code> instructions. This distinction requires<br>
an explicit bytecode to fix up Q/L mismatches; the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">checkcast</code><br>
bytecode serves this purpose. That means checkcast requires the<br>
ability to work with privatized types. It requires us to make the<br>
dynamic permission check when other bytecodes try to use the<br>
privatized type. All this seems acceptable, but we could try to make<br>
a different design which <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> resolution fails immediately<br>
if it contains an inaccessible Q-descriptor. That design might<br>
require a new bytecode which does what <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">checkcast</code> does today on a<br>
Q-descriptor.)</p>
<p dir="auto">Meanwhile, arrays are rich sources of non-constructed zero values.<br>
They appear in bytecode as follows:</p>
<ul>
<li>A <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> array construction uses <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">anewarray</code> with a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> type for the Q-descriptor; this is new to Valhalla.</li>
<li>Such an array construction may also use <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">multianewarray</code> with an appropriate array type.</li>
<li>An array element is read from heap to stack by <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aaload</code>; the verifier type of the stacked value is copied from the verifier type of the array itself.</li>
<li>An array element is written from stack to heap by <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aastore</code>; the verifier type of the stored value is merely constrained to the type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object</code>.</li>
</ul>
<p dir="auto">Note that there are no static type annotations on array access<br>
instruction. The practical impact of this is that, if an array of a<br>
privatized type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is passed outside of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>, then any values in<br>
that array become accessible outside of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>. Moreover, if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is<br>
non-atomic, clients may be able to inflict data races on the array.</p>
<p dir="auto">Thus, the best point of control over misuse of arrays is their<br>
<em>creation</em>, not their <em>access</em>. Array creation is controlled by<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> constant pool entries and their access checking.<br>
When an <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">anewarray</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">multianewarray</code> tries to create an array,<br>
the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> constant pool entry it uses must be consulted<br>
to see if the element type is privatized and inaccessible to the<br>
current class, and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">IllegalAccessError</code> thrown if that is the case.</p>
<p dir="auto">All this leads to special rules for resolving an entry of the form<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class["QC;"]</code>. When resolving such a constant, the class<br>
file for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is loaded, and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is access checked against the current<br>
class. (This is just what happens when <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class["C"]</code> gets<br>
resolved.) Next, the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ValueClass</code> attribute for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is examined; it<br>
must exist, and if it indicates privatization of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, then access<br>
is checked for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> against the current class.</p>
<p dir="auto">If that access to a privatized companion would fail, no exception is<br>
thrown, but the constant pool entry is resolved into a special<br>
restricted state. Thus, a resolved constant pool entry of the form<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class["QC;"]</code> can have the following states:</p>
<ul>
<li>Error, because <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is inaccessible or doesn't exist or is not a value class.</li>
<li>Full resolution, so <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is ready for general use in the current class.</li>
<li>Restricted resolution, so <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is ready for restricted use in the current class.</li>
</ul>
<p dir="auto">That last state happens when <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is accessible but <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is not.</p>
<p dir="auto">Likewise, a constant pool entry of the form <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class["[QC;"]</code><br>
(or a similar form with more leading array brackets) can have three<br>
states, error, full resolution, and restricted resolution.</p>
<p dir="auto">Pre-Valhalla <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> entries which do not mention<br>
Q-descriptors have only two resolved states, error and full<br>
resolution.</p>
<p dir="auto">As required above, the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">checkcast</code> bytecode treats full resolution and<br>
restricted resolution states the same.</p>
<p dir="auto">But when the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">anewarray</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">multianewarray</code> instruction is executed,<br>
it consults throws an access error if its <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> is not<br>
fully resolved (either it is an error or is restricted). This is how<br>
the JVM prevents creation of arrays whose component type is an<br>
inaccessible value companion type, even if the class file does<br>
not correspond to correct Java source code.</p>
<p dir="auto">Here are all the classfile constructs that could refer to a<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> constant in the restricted state, and whether they<br>
respect it (throwing <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">IllegalAccessError</code>):</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">checkcast</code> ignores the restriction and proceeds</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">instanceof</code> ignores the restriction (consistent with <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">checkcast</code>)</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">anewarray</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">multianewarray</code> respect the restriction and throw</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ldc</code> throws (consistent with <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code> in source code)</li>
<li>bootstrap arguments throw (consistent with <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ldc</code>)</li>
<li>verifier types ignore the restriction and continue checking</li>
<li><strong>(FIXME: There must be more than this.)</strong></li>
</ul>
<p dir="auto">Q-descriptors not in <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> constants are naturally immune<br>
to privatization restrictions. In particular, <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Methodtype</code><br>
constants can successfully refer to mirrors to privatized companions.</p>
<p dir="auto">Uses of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Class</code> constants which forbid Q-descriptors and<br>
their arrays are also naturally immune, since they will never<br>
encounter a constant resolved in the restricted state. These include<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">new</code>, <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aconst_init</code>, the class sub-operands of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT_Methodref</code><br>
and its friends, exception catch-types, and various attributes like<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">NestHost</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">InnerClasses</code>: All of the above are allowed to refer<br>
only to proper classes, and not to their value companions or arrays.</p>
<p dir="auto">Nevertheless, a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aconst_init</code> bytecode must throw an access error when<br>
applied to a class with an inaccessible privatized value companion.<br>
This is worth noting because the constant pool entry for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aconst_init</code><br>
does <em>not</em> mention a Q-descriptor, unlike the array construction<br>
bytecodes.</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">Perhaps regular class constants of the form <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT["C"]</code> would</p>
</blockquote>
<p dir="auto">also benefit slightly from a restricted state, which would be<br>
significant <em>only</em> to the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aconst_init</code> bytecode, and ignored by all<br>
the above "naturally immune" usages. If a JVM implementation takes<br>
this option, the same access check would be performed and recorded for<br>
both <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT["C"]</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">CONSTANT["QC;"]</code>, but would be respected<br>
only by <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">withvalue</code> (for the former) and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">anewarray</code> and the other<br>
cases noted above (for the latter but <em>not</em> the former). On the other<br>
hand, the particular issue would become moot if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">aconst_init</code>, like<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">withfield</code>, were restricted to the nest of its class, because then<br>
privatization would not matter.</p>
<p dir="auto">The net effect of these rules, so far, is that neither source code nor<br>
class files can directly make uninitialized variables of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>,<br>
if the code or class file was not granted access to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> via <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>.<br>
Specifically, fields of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> cannot be declared nor can arrays<br>
of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> be constructed.</p>
<p dir="auto">This includes class files as correctly derived from valid source code<br>
or as "spun" by dodgy compilers or even as derived validly from old<br>
source code that has changed (and revoked some access).</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">Remember that new nestmates can be injected at runtime via the</p>
</blockquote>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup</code> API, which checks access and then loads new code that enjoys<br>
the same access. The level of access depends in detail on the<br>
selection of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ClassOption.NESTMATE</code> (for nestmate injection) or not<br>
(for package-mate injection). The JVM uses common rules for these<br>
injected nestmates or package-mates and for normally compiled ones.</p>
<p dir="auto">There are no restrictions on the use of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>, beyond the basic<br>
access restrictions imposed by the language and JVM on the name <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>.<br>
Access checks for regular references to classes and interfaces are<br>
unchanged throughout all of the above.</p>
<p dir="auto">There are more holes to be plugged, however. It will turn out that<br>
arrays are once again a problem. But first let's examine how<br>
reflection interacts with companion types and access control.</p>
<h2 style="font-size: 1.2em;">Privatization and APIs</h2>
<p dir="auto">Beyond the language there are libraries that must take account of the<br>
privatization of value companions. We start on the shared boundary<br>
between language and libraries, with reflection.</p>
<h3 style="font-size: 1.1em;">Reflecting privatization</h3>
<p dir="auto">Every companion type is reflected by a Java class mirror of type<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.Class</code>. A Java class mirror <em>also</em> represents the class<br>
underlying the type. The distinction between the concept of class and<br>
companion type is relatively uninteresting, except for a value class<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>, which has two companion types and thus two mirrors.</p>
<p dir="auto">In Java source code the expression <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.class</code> obtains the mirror for<br>
both <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> and its companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>. The expression <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code><br>
obtains the mirror for the value companion, if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is a value class.<br>
Both expressions check access to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> as a whole, and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code><br>
<em>also</em> checks access to the value companion (if it was privatized).</p>
<p dir="auto">But it is a generally recognized fact that Java class mirrors are less<br>
secure than the Java class types that the mirrors represent. It is<br>
easy to write code that obtains a mirror on a class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> without<br>
directly mentioning the name <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> in source code. One can use<br>
reflective lookup to get such mirrors, and without even trying one may<br>
also "stumble upon" mirrors to inaccessible classes and companion<br>
types. Here are some simple examples:</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">Class<?> lookup() {
var name = "java.util.Arrays$ArrayList";
//or name = "java.lang.AbstractStringBuilder";
//> java.lang.invoke.MethodHandles.lookup().findClass(name); //ERROR
return Class.forName(name); //OK!
}
Class<?> stumble1() {
//> return java.util.Arrays.ArrayList.class; //ERROR
return java.util.Arrays.asList().getClass(); //OK!
}
Class<?> stumble2() {
//> return java.lang.AbstractStringBuilder.class; //ERROR
return StringBuilder.class.getSuperclass(); //OK!
}
Class<?> stumble3() {
//> return C.val.class; //ERROR if C.val is privatized
return C.ref.class.asValueType(); //OK!
}
</code></pre>
<p dir="auto">Therefore, access checking class names is not and cannot be the whole<br>
story for protecting classes and their companion types from reflective<br>
misuse. If a mirror is obtained that refers to an inaccessible<br>
non-public class or privatized companion, the mirror will "defend<br>
itself" against illegal access by checking whether the caller has<br>
appropriate permissions. The same goes for method, constructor, and<br>
field mirrors derived from the class mirror: You can reflect a method<br>
but when you try to call it all of the access checks (including the<br>
check against the class) are enforced against you, the caller of the<br>
reflective API.</p>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">The checking of the caller has two possible shapes. Either a caller</p>
</blockquote>
<p dir="auto">sensitive method looks directly at its caller, or the call is<br>
delegated through an API that requires negotiation with a<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles.Lookup</code> object that was previously checked against a<br>
caller.</p>
<p dir="auto">Now, if a class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is accessible but its value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is<br>
privatized, all of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s public methods and other API points are<br>
accessible (via both companion types), but access is limited to those<br>
very specific operations that could create non-constructed instances<br>
(via a variable of companion type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>). And this boils down<br>
to a limitation on array creation. If you cannot use either source<br>
code or reflection to create an array of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code>, then you<br>
cannot create the conditions necessary to build non-constructed<br>
instances.</p>
<p dir="auto">Reflective APIs should be available to report the declared properties<br>
of reference companions. It is enough to add the following two methods:</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class::isNonAtomic</code> is true only of mirrors of value companions</li>
</ul>
<p dir="auto">which have been declared non-atomic. On some JVM implementations it<br>
<em>may</em> additionally be true of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">long.class</code> and/or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">double.class</code>.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class::getModifiers</code>, when applied to a mirror of a value</li>
</ul>
<p dir="auto">companion, will return a modifier bit-mask that reflects the<br>
declared access. (This is compatible with the current behavior of<br>
HotSpot for primitive mirrors, which appear as if they were somehow<br>
declared <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">public</code>, with <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">abstract</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">final</code> thrown in to boot.)</p>
<p dir="auto">(Note that most reflective access checking should take care to work<br>
with the reference mirror, not the value mirror, as the modifier bits<br>
of the two mirrors might differ.)</p>
<h3 style="font-size: 1.1em;">Privatization and arrays</h3>
<p dir="auto">There are a number of standard API points for creating Java array<br>
objects. When they create arrays containing uninitialized elements,<br>
then a non-constructed default value can appear. Even when they<br>
create properly initialized arrays, if the type is declared<br>
non-atomic, then non-constructed values can be created by races.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.reflect.Array::newInstance</code> takes an element mirror and length and builds an array. The elements of the returned array are initialized to the default value of the selected element type.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Arrays::copyOf</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">copyOfRange</code> can extend the length of an existing array to include new uninitialized elements.</li>
<li>A special overloading of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Arrays::copyOf</code> can request a different type of the new array copy.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Collection::toArray</code> (an interface method) may extend the length of an existing array, but does not add uninitialized elements.</li>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.invoke.MethodHandles.arrayConstructor</code> creates a method handle that creates uninitialized arrays of a given type, as if by the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">anewarray</code> bytecode.</li>
<li>The serialization API contains an operator for materializing arrays of arbitrary type from the wire format.</li>
</ul>
<p dir="auto">The basic policy for all these API points is to conservatively limit<br>
the creation of arrays of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is not public.</p>
<ul>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.reflect.Array::newInstance</code> will throw<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">IllegalArgumentException</code> if the element type is privatized.<br>
(See below for a possible caller-sensitive enhancement.)</p>
</li>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Arrays::copyOf</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">copyOfRange</code> will throw instead of<br>
creating uninitialized elements, if the element type is<br>
privatized. If only previously existing array elements are<br>
copied, there is no check, and this is a use common case (e.g., in<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">ArrayList::toArray</code>).</p>
</li>
<li>
<p dir="auto">The special overloading of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Arrays::copyOf</code> will refuse<br>
to create an array of any non-atomic privatized type. (This<br>
refusal protects against non-constructed values arising from data<br>
races.) It also incorporates the restrictions of its sibling<br>
methods, against creating uninitialized elements (even of an<br>
atomic type).</p>
</li>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.invoke.MethodHandles.arrayConstructor</code> will refuse to<br>
create a factory method handle if the element type is privatized.</p>
</li>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Collection::toArray</code> needs implementation review; as it<br>
is built on top of the previous API points, it may possibly fail<br>
if asked to lengthen an array of privatized type. Note that many<br>
methods of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">toArray</code> use <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays.copyOf</code> in a safe manner, which<br>
does <em>not</em> create uninitialized elements.</p>
</li>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.stream.Stream::toArray</code>, the various <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">List::toArray</code>,<br>
and other clients of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays::copyOf</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Array::newInstance</code> need<br>
implementation review. Where a generic API is involved, the<br>
assumption is often that non-flat reference arrays are being<br>
created, and in that case no outage is possible, since reference<br>
companion arrays can always be freely created. For specialized<br>
generics with flat types, additional implementation work is<br>
required, in general, to ensure that flat arrays can be created by<br>
parties with the right to do so.</p>
</li>
<li>
<p dir="auto">The serialization API should restrict its array creation operator.<br>
Serialization methods should not attempt to serialize flat arrays<br>
either. It is enough to serialize arrays of the reference type.</p>
</li>
</ul>
<p dir="auto"><strong>API ISSUE #1:</strong> Should we relax construction rules for zero-length<br>
arrays? This would add complexity but might be a friendly move for<br>
some use cases. A zero-length array cannot expose non-constructed<br>
values. It may, however, serve as a misleading "witness" that some<br>
code has gained permission to work with flat arrays. It's safer to<br>
disallow even zero-length arrays.</p>
<p dir="auto"><strong>API ISSUE #2:</strong> What about public value companions of non-public<br>
inaccessible classes? In source code, we do not allow arrays of<br>
private classes to be made, or of their their public value companions.<br>
Should we be more permissive in this case? We could specify that<br>
where a value companion has to be checked against a client, its<br>
original class gets checked as well; this would exclude some use cases<br>
allowed by the above language, which only takes effect if the<br>
companion is privatized. An extra check for a public companion seems<br>
like busy-work and a source of unnecessary surprises, though. Let's<br>
not.</p>
<p dir="auto">There are probably legitimate use cases for arrays of privatized<br>
types, with which the new restrictions on the above API points would<br>
interfere. So as a backup, we will make API adjustments to work with<br>
privatized array types, with an extra handshake to perform the access<br>
check (via either caller sensitivity or negotiation with an instance<br>
of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles.Lookup</code>).</p>
<ul>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.reflect.Array::newInstance</code> should probably be made<br>
caller sensitive, so it can refrain from throwing if a privatized<br>
element type is accessible to the caller. (Alternatively, a new<br>
caller-sensitive API point could made, such as<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Array::newFlatInstance</code>. But a new API point seems unnecessary<br>
in this case, and caller-sensitivity is common practice in this<br>
method's package.) Note that, as is typical of core reflection<br>
API points, <em>many uses</em> of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">newInstance</code> will not benefit from<br>
the caller sensitivity.</p>
</li>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util.Arrays::copyOf</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">copyOfRange</code> may be joined by<br>
additional "companion friendly" methods of a similar character<br>
which fill new array elements with some other specified fill<br>
value, and/or which cyclically replicate the contents of the<br>
original array, and/or which call a functional interface to<br>
provide missing elements. The details of this are a matter for<br>
library designers to decide. Adding caller sensitivity to<br>
these API points is probably the wrong move.</p>
</li>
<li>
<p dir="auto"><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.invoke.MethodHandles::arrayConstructor</code> will be joined<br>
by a method of the same name on <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles.Lookup</code> which<br>
performs a companion check before allowing the array constructor<br>
method handle to be returned. It will <em>not check the class</em>, just<br>
the companion. Note that the use of caller sensitivity in the<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup</code> API is concentrated on the factory method <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::lookup</code>,<br>
which is the starting point for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup</code>-based negotiation.</p>
</li>
</ul>
<h3 style="font-size: 1.1em;">Miscellaneous privatization checks</h3>
<p dir="auto">Besides newly-created or extended arrays, there are a few API points<br>
in <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.lang.invoke</code> which expose default values of reflectively<br>
determined types. Like the array creation methods, they must simply<br>
refuse to expose default values of privatized value companions.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::zero</code> and <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::empty</code> will simply</li>
</ul>
<p dir="auto">refuse to produce a result of a privatized <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> type. Clients<br>
with a legitimate need to produce such default values can use<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::filterReturnValue</code> and/or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::constant</code><br>
to create equivalent handles, assuming they already possess the<br>
default value.</p>
<ul>
<li><code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::explicitCastArguments</code> will refuse to convert from</li>
</ul>
<p dir="auto">a nullable reference to a privatized <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> type. Clients with a<br>
legitimate need to convert nulls to privatized values can use<br>
conditional combinators to do this "the hard way".</p>
<ul>
<li>The method <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::accessCompanion</code> will be defined analogously</li>
</ul>
<p dir="auto">to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::accessClass</code>. If <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::accessClass</code> is applied to a<br>
companion, it will check both the class and the companion, whereas<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::accessCompanion</code> will look only at the possible<br>
privatization of the companion. (Thus it can simply refer to<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Reflection::verifyCompanionType</code>.)</p>
<p dir="auto">To support reflective checks against array elements which may be<br>
privatized companion types, an internal method of the form<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">jdk.internal.reflect.Reflection::verifyCompanionType</code> may be defined.<br>
It will pass any reference type (regardless of class accessibility)<br>
and for a value companion it will check access of the companion (but<br>
not the class itself).</p>
<h3 style="font-size: 1.1em;">Building companion-safe APIs</h3>
<p dir="auto">The method <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::arrayConstructor</code> gives enough of a "hook" to<br>
create all kinds of safe but friendly APIs in privileged JDK code.<br>
The methods in <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">java.util</code> could make use of this privileged API to<br>
quickly adapt their internal code to create arrays in cases they are<br>
refused by the existing methods <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Array.newInstance</code> and<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays.copyOf</code>.</p>
<p dir="auto">For example, a checked method <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles.Lookup::defaultValue(C)</code><br>
may be added to provide the default value <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> if its companion<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is accessible. It will operate as if it first creates a<br>
one-element array of the desired type, and then loads the element.</p>
<p dir="auto">Or, a caller-sensitive method <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class::defaultValue</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class::newArray</code><br>
could be added which check the caller and return the requested result.<br>
All such methods can be built on top of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles.Lookup</code>.</p>
<p dir="auto">In general, a library API may be designed to preserve some aspect of<br>
companion safety, as it allows untrusted code to work with arrays of<br>
privatized value type, while preventing non-constructed values of that<br>
type from being materialized. Each such safe and friendly API has to<br>
make a choice about how to prevent clients from creating<br>
non-constructed states, or perhaps how to allow clients to gain<br>
privilege to do so. Some points are worth remembering:</p>
<ul>
<li>An unprivileged client must not obtain <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is privatized.</li>
<li>An unprivileged client must not obtain a non-empty <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> array if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is privatized and non-atomic.</li>
<li>It's safe to build new (non-empty, mutable) arrays from (non-empty, mutable) old arrays, if the default is not injected.</li>
<li>If a new array is somehow frozen or wrapped so as be effectively immutable, it is safe as long as it does not expose <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> values.</li>
<li>If a value companion is <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">public</code>, there is no need for any restriction.</li>
<li>Also, unrestricted use can be gated by a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup</code> object or caller sensitivity.</li>
</ul>
<blockquote style="margin: 0 0 5px; padding-left: 5px; border-left: 2px solid #777777; color: #777777;">
<p dir="auto">In the presence of a reconstruction capability, either in the</p>
</blockquote>
<p dir="auto">language or in a library API or as provided by a single class,<br>
avoiding non-constructable objects includes allowing legitimate<br>
reconstruction requests; each legitimate reconstruction request must<br>
somehow preserve the intentions of the class's designer.<br>
Reconstruction should act as if field values had been legitimately<br>
(from <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s API) extracted, transformed, and then again legitimately<br>
(to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s API) rebuilt into an instance of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>. Serialization is an<br>
example of reconstruction, since field values can be edited in the<br>
wire format. Proposed <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">with</code> expressions for records are another<br>
example of reconstruction. The <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">withfield</code> bytecode is the primitive<br>
reconstruction operator, and must be restricted to nestmates of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code><br>
since it can perform all physically possible field updates.<br>
Reconstruction operations defined outside of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> must be designed with<br>
great care if they use elevated privileges beyond what <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> provides<br>
directly.</p>
<h2 style="font-size: 1.2em;">Summary of user model</h2>
<p dir="auto">A value class <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> has a value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> which denotes the<br>
null-hostile (zero-initialized) fully flattenable value type for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>.</p>
<p dir="auto">Like other type members of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>, <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> can be declared with an access<br>
modifier (<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">public</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">private</code> or neither). It is therefore quite<br>
possible that clients of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> might be prevented from using the<br>
companion type.</p>
<p dir="auto">The operations on <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> are almost the same as the operations on<br>
plain <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> (<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>), so a private <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is usually not a burden.</p>
<p dir="auto">Operations which are unique to <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, and which therefore may<br>
be restricted to you, are:</p>
<ul>
<li>declaring a field of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code></li>
<li>making an array with element type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code></li>
<li>getting the default flat value <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code></li>
<li>asking for the mirror <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code></li>
</ul>
<p dir="auto">Library routines which create empty flattenable arrays of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code><br>
might not work as expected, when <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is not public. You'll have<br>
to find a workaround, such as:</p>
<ul>
<li>use a plain <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> reference array to hold your data</li>
<li>use a different API point which is friendly to privatie <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> types</li>
<li>ask <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> politely to build such an array for you</li>
<li>crack into <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> with a reflective API and build your own</li>
</ul>
<p dir="auto">If you look closely at the code for <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>, you might noticed that it<br>
uses its private type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> in its public API. This is allowed.<br>
Just be aware that null values will not flow through such API points.<br>
When you get a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> value into your own code, you can work on it<br>
perfectly freely with the type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> (which is <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.ref</code>).</p>
<p dir="auto">If a value companion <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">public</code>, the class has<br>
declared that it is willing to encounter its own default value<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> coming from untrusted code. If it is declared <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">private</code>,<br>
only the class's own nest can work with <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code>. If the value<br>
companion is neither public nor private, the class has declared that<br>
it is willing to encounter its own default within its own package.</p>
<p dir="auto">If a class has declared its companion non-atomic, it is willing to<br>
encounter states arising from data races (across multiple fields) in<br>
the same places it is willing to encounter its default value.</p>
<h3 style="font-size: 1.1em;">Summary of restrictions</h3>
<p dir="auto">From the implementation point of view, the salient task is restricting<br>
clients from illegitimately obtaining non-constructed values of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>,<br>
if the author of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> has asked for such restrictions. (Recall that a<br>
<em>non-constructed value</em> of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> is one obtained without using <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>'s<br>
constructor or other public API.) Here are the generally enforced<br>
restrictions regarding a privatized type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>:</p>
<ul>
<li>You cannot mention the name <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> in code.</li>
<li>You cannot create and load bytecodes which would implement such a mention.</li>
<li>You cannot obtain <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> from a mirror of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>.</li>
<li>You cannot create a new <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> array from a mirror of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>.</li>
<li>You cannot lengthen an existing <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> array to contain uninitialized elements.</li>
<li>You cannot copy an existing array as a new <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code> array, if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is declared non-atomic.</li>
</ul>
<p dir="auto">Even so, let us suppose you are an accident-prone client of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>.<br>
Ignoring the above restrictions, you might go about obtaining a<br>
non-constructed value of <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> in several ways, and there is an<br>
answer from the system in each case that stops you:</p>
<ul>
<li>You can mention the <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> directly in code, in various ways.</li>
<li>After obtaining the mirror <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code> (by one of several means), you can call <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Class::defaultValue</code>, <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::zero</code>, or a similar API point.</li>
<li>If you can declare a field of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> directly you can extract an initial value (or a data-race result, if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is non-atomic).</li>
<li>If you can indirectly create an array of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>, you can extract an initial value (or a data-race result, if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> is non-atomic).</li>
</ul>
<p dir="auto">And there are a number of ways you might attempt to indirectly create<br>
an array of type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val[]</code>:</p>
<ul>
<li>Indirectly create it from a mirror using <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Array::newInstance</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays::copyOf</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::arrayConstructor</code> or another similar API point.</li>
<li>Create it from a pre-existing array of the same type using <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Object::clone</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays::copyOf</code> or another similar API point.</li>
<li>Specify such an array on a serialization wire format and deserialize it.</li>
</ul>
<p dir="auto">Using <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.default</code> directly is blocked if <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code> privatizes its<br>
value companion, unless you are coding a nestmate or package-mate of<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C</code>. These checks are applied both at compile time and when the JVM<br>
resolves names, so they apply equally to source code and bytecodes<br>
created by any means whatsoever.</p>
<p dir="auto">There are no realistic restrictions on obtaining a mirror to a<br>
companion type <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. (Accidental and casual direct use of<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val.class</code> is prevented by access restrictions on the type name<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">C.val</code>. But there are many ways to get around this limitation.)<br>
Therefore any method or API which could violate the above generally<br>
enforced restrictions must perform an appropriate dynamic access check<br>
on behalf of its mirror argument.</p>
<p dir="auto">Such a dynamic access check can be made negotiable by an appeal to<br>
caller sensitivity or a <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup</code> check, so a correctly configured call<br>
can avoid the restriction. For some simple methods (perhaps<br>
<code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Arrays::copyOf</code> or <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">MethodHandles::zero</code>) there is no negotiation.<br>
Depending on the use case, access failure can be worked around via a<br>
"negotiable" API point like <code style="margin: 0; padding: 0 0.4em; border-radius: 3px; background-color: #F7F7F7;">Lookup::arrayConstructor</code>.</p>
</div></div></body>
</html>