RFC: 8204690: Simplify usage of Access API

Wed Jun 13 10:29:09 UTC 2018

Sounds good to me. Thanks for taking care about this.

StefanK

On 2018-06-11 21:36, Kim Barrett wrote:
> JDK-8204690 is an enhancement request for simplifing the usage of the
> Access API.  This RFE comes out of some discussions within the Oracle
> runtime and GC teams about difficulties encountered when using the
> Access API.  We now have a concrete set of changes to propose (rather
> than just vague complaints), described in that RFE, which I'm
> duplicating below for further discussion.
> 
> Most of the proposed changes are technically straight-forward; many
> are just changes of nomenclature. However, because they are name
> changes, they end up touching a bunch of files, including various
> platform-specific files.  So we'll be asking for help with testing.
> 
> We want to move ahead with these changes ASAP, because of the impact
> they will have to backporting to JDK 11 if not included in that
> release. However, a few of the changes significantly intersect other
> changes that are soon to be pushed to JDK 11, so some amount of
> scheduling will be needed to minimize overall work.
> 
> Here's the description from the RFE:
> 
> ----------
> 
> Simplify usage of Access API
> 
> With 6+ months of usage of the Access API, some usage issues have been
> noted. In particular, there are some issues around decorator names and
> semantics which have caused confusion and led to some long discussions.
> While the underlying strategy is sound, there are some changes that would
> simplify usage. This proposal is in part the result of attempting to create
> a guide for choosing the decorators for some use of the Access API.
> 
> We currently have several categories of decorators, with some categories
> having entries with overlapping semantics. We'd like to have a set of
> categories from which one chooses exactly one entry, and it should be
> "obvious" which one to choose for a given access.
> 
> The first step is to determine where the operand is located. We presently
> have the following decorators to indicate the Access location: IN_HEAP,
> IN_HEAP_ARRAY, IN_ROOT, IN_CONCURRENT_ROOT, and IN_ARCHIVE_ROOT. Some of
> these overlap with or imply others; the goal is to have a disjoint set.
> 
> IN_CONCURRENT_ROOT has generated much discussion about when and how it
> should be used. This might be better modelled as a Barrier Strength
> decorator, e.g. in the AS_ category. It was placed among the location
> decorators with the idea that some Access-roots would be identified as being
> fully processed during a safe-point (and so would not require GC barriers),
> while others (the "concurrent" roots) would require GC barriers. There was a
> question of whether we needed more fine-grained decorators, or whether just
> two categories that are the same for all collectors would be sufficient. So
> far, we've gotten along without introducing further granularity. But we've
> also found no significant need for the distinction at all.
> 
> Proposal 1: IN_CONCURRENT_ROOT should be eliminated, and the corresponding
> behavior should be the default.
> 
> Proposal 2: IN_ARCHIVE_ROOT should be eliminated; see JDK-8204585.
> 
> IN_HEAP_ARRAY is effectively an additional orthogonal property layered over
> IN_HEAP. It would be better to actually make it an orthogonal property.
> 
> Proposal 3: Remove IN_HEAP_ARRAY and add IS_ARRAY with similar semantics.
> (IS_ARRAY might only be valid in conjunction with IN_HEAP.)
> 
> The use of "root" here differs from how that term is usually used in the
> context of GC. In particular, while GC-roots are Access-roots, not all
> Access-roots are GC-roots. This is a frequent source of confusion.
> 
> Proposal 4: The use of "root" by Access should be replaced by "native". So
> IN_ROOT => IN_NATIVE, and RootAccess<> => NativeAccess<>.
> 
> The second step is to determine the reference strength. The current API has
> been working well here. We have ON_STRONG_OOP_REF, ON_WEAK_OOP_REF,
> ON_PHANTOM_OOP_REF, and ON_UNKNOWN_OOP_REF, with ON_STRONG_OOP_REF being the
> default. No changes are being proposed in this area.
> 
> Another step is to determine the barrier strength. We presently have the
> following decorators for this: AS_RAW, AS_DEST_NOT_INITIALIZED,
> AS_NO_KEEPALIVE, and AS_NORMAL. AS_DEST_NOT_INITIALIZED is somewhat out of
> place here, describing a property of the value rather than the access. It
> would be better to make it an orthogonal property. The existing name is also
> a little awkward, especially when turned into a variable and logically
> negated, e.g.
> 
>    bool is_dest_not_initialized = ...;
>    ... !is_dest_not_initialized ...
> 
> Proposal 5: Rename AS_DEST_NOT_INITIALIZED to IS_DEST_UNINITIALIZED.
> 
> The fourth step is to determine the memory order. The current API has been
> working well here. We have MO_UNORDERED, MO_VOLATILE, MO_RELAXED,
> MO_ACQUIRE, MO_RELEASE, MO_SEQ_CST. No changes are being proposed in this
> area.
> 
> In addition, we presently have OOP_NOT_NULL, all on its own in a separate
> category. There's no need for this separate category, and this can be
> renamed to be similar to other orthogonal properties proposed above.
> 
> Proposal 6: Rename OOP_NOT_NULL to IS_NOT_NULL.  Remove OOP_DECORATOR_MASK.
> 
> Proposal 7: Add IS_DECORATOR_MASK, containing the values for IS_ARRAY,
> IS_NOT_NULL, and IS_DEST_UNINITIALIZED.
> 
> There are also decorators for annotating arraycopy. These are highly tied in
> to the code, and are not discussed here.
> 
> With these changes, the process of selecting the decorators for an access
> consists of first selecting one decorator in each of the following
> categories:
> 
> (1) Operand location: IN_NATIVE, IN_HEAP. There is no default; one or the
> other must be explicitly specified. However, rather than using the
> decorators directly, use the NativeAccess<> and HeapAccess<> classes.
> 
> (2) Access strength: AS_NORMAL, AS_RAW, AS_NO_KEEPALIVE. The default
> is AS_NORMAL.  When accessing a primitive (non-object) value, use
> AS_RAW.
> 
> (3) Reference strength (if not raw access): ON_STRONG_OOP_REF,
> ON_WEAK_OOP_REF, ON_PHANTOM_OOP_REF, ON_UNKNOWN_OOP_REF. The default is
> ON_STRONG_OOP_REF. This decorator is ignored and should be left empty if the
> access strength is AS_RAW.
> 
> (4) Memory ordering: MO_UNORDERED, MO_VOLATILE, MO_RELAXED, MO_ACQUIRE,
> MO_RELEASE, MO_SEQ_CST. The default is MO_UNORDERED.
> 
> Then, add any of the following "flag" decorators that are appropriate:
> IS_ARRAY, IS_NOT_NULL, IS_DEST_UNINITIALIZED. The default for these is that
> the flag is unset.
>   Simplify usage of Access API
> 
> With 6+ months of usage of the Access API, some usage issues have been
> noted. In particular, there are some issues around decorator names and
> semantics which have caused confusion and led to some long discussions.
> While the underlying strategy is sound, there are some changes that would
> simplify usage. This proposal is in part the result of attempting to create
> a guide for choosing the decorators for some use of the Access API.
> 
> We currently have several categories of decorators, with some categories
> having entries with overlapping semantics. We'd like to have a set of
> categories from which one chooses exactly one entry, and it should be
> "obvious" which one to choose for a given access.
> 
> The first step is to determine where the operand is located. We presently
> have the following decorators to indicate the Access location: IN_HEAP,
> IN_HEAP_ARRAY, IN_ROOT, IN_CONCURRENT_ROOT, and IN_ARCHIVE_ROOT. Some of
> these overlap with or imply others; the goal is to have a disjoint set.
> 
> IN_CONCURRENT_ROOT has generated much discussion about when and how it
> should be used. This might be better modelled as a Barrier Strength
> decorator, e.g. in the AS_ category. It was placed among the location
> decorators with the idea that some Access-roots would be identified as being
> fully processed during a safe-point (and so would not require GC barriers),
> while others (the "concurrent" roots) would require GC barriers. There was a
> question of whether we needed more fine-grained decorators, or whether just
> two categories that are the same for all collectors would be sufficient. So
> far, we've gotten along without introducing further granularity. But we've
> also found no significant need for the distinction at all.
> 
> Proposal 1: IN_CONCURRENT_ROOT should be eliminated, and the corresponding
> behavior should be the default.
> 
> Proposal 2: IN_ARCHIVE_ROOT should be eliminated; see JDK-8204585.
> 
> IN_HEAP_ARRAY is effectively an additional orthogonal property layered over
> IN_HEAP. It would be better to actually make it an orthogonal property.
> 
> Proposal 3: Remove IN_HEAP_ARRAY and add IS_ARRAY with similar semantics.
> (IS_ARRAY might only be valid in conjunction with IN_HEAP.)
> 
> The use of "root" here differs from how that term is usually used in the
> context of GC. In particular, while GC-roots are Access-roots, not all
> Access-roots are GC-roots. This is a frequent source of confusion.
> 
> Proposal 4: The use of "root" by Access should be replaced by "native". So
> IN_ROOT => IN_NATIVE, and RootAccess<> => NativeAccess<>.
> 
> The second step is to determine the reference strength. The current API has
> been working well here. We have ON_STRONG_OOP_REF, ON_WEAK_OOP_REF,
> ON_PHANTOM_OOP_REF, and ON_UNKNOWN_OOP_REF, with ON_STRONG_OOP_REF being the
> default. No changes are being proposed in this area.
> 
> Another step is to determine the barrier strength. We presently have the
> following decorators for this: AS_RAW, AS_DEST_NOT_INITIALIZED,
> AS_NO_KEEPALIVE, and AS_NORMAL. AS_DEST_NOT_INITIALIZED is somewhat out of
> place here, describing a property of the value rather than the access. It
> would be better to make it an orthogonal property. The existing name is also
> a little awkward, especially when turned into a variable and logically
> negated, e.g.
> 
>    bool is_dest_not_initialized = ...;
>    ... !is_dest_not_initialized ...
> 
> Proposal 5: Rename AS_DEST_NOT_INITIALIZED to IS_DEST_UNINITIALIZED.
> 
> The fourth step is to determine the memory order. The current API has been
> working well here. We have MO_UNORDERED, MO_VOLATILE, MO_RELAXED,
> MO_ACQUIRE, MO_RELEASE, MO_SEQ_CST. No changes are being proposed in this
> area.
> 
> In addition, we presently have OOP_NOT_NULL, all on its own in a separate
> category. There's no need for this separate category, and this can be
> renamed to be similar to other orthogonal properties proposed above.
> 
> Proposal 6: Rename OOP_NOT_NULL to IS_NOT_NULL.  Remove OOP_DECORATOR_MASK.
> 
> Proposal 7: Add IS_DECORATOR_MASK, containing the values for IS_ARRAY,
> IS_NOT_NULL, and IS_DEST_UNINITIALIZED.
> 
> There are also decorators for annotating arraycopy. These are highly tied in
> to the code, and are not discussed here.
> 
> With these changes, the process of selecting the decorators for an access
> consists of first selecting one decorator in each of the following
> categories:
> 
> (1) Operand location: IN_NATIVE, IN_HEAP. There is no default; one or the
> other must be explicitly specified. However, rather than using the
> decorators directly, use the NativeAccess<> and HeapAccess<> classes.
> 
> (2) Access strength: AS_NORMAL, AS_RAW, AS_NO_KEEPALIVE. The default is AS_NORMAL.  When accessing a primitive (non-object) value, use AS_RAW.
> 
> (3) Reference strength (if not raw access): ON_STRONG_OOP_REF,
> ON_WEAK_OOP_REF, ON_PHANTOM_OOP_REF, ON_UNKNOWN_OOP_REF. The default is
> ON_STRONG_OOP_REF. This decorator is ignored and should be left empty if the
> access strength is AS_RAW.
> 
> (4) Memory ordering: MO_UNORDERED, MO_VOLATILE, MO_RELAXED, MO_ACQUIRE,
> MO_RELEASE, MO_SEQ_CST. The default is MO_UNORDERED.
> 
> Then, add any of the following "flag" decorators that are appropriate:
> IS_ARRAY, IS_NOT_NULL, IS_DEST_UNINITIALIZED. The default for these is that
> the flag is unset.
> 