RFR: 8248877: Document API contract for MetaspaceObj subtypes

[Ioi Lam]

On Thu, 3 Jun 2021 14:14:54 GMT, Coleen Phillimore <coleenp at openjdk.org> wrote:

>> This PR adds documentation for the (non-virtual) functions that subtypes of MetaspaceObj are required to implement in order for certain templates to work properly. 
>> 
>> Requested by @rose00 (sorry I took a long time ....).
>
> src/hotspot/share/memory/allocation.hpp line 277:
> 
>> 275:   //
>> 276:   // The following functions are required by MetadataFactory::free_metadata():
>> 277:   //   bool on_stack() { return false; } // DEBUG only
> 
> I don't think the // DEBUG only comment is correct.  on_stack is used in product mode.  Can you remove this?

Hmm .... in product code, there's no use of `MetaspaceObj::on_stack()`, but there's use of `Metadata::on_stack()`.

-------------

PR: https://git.openjdk.java.net/jdk/pull/4327