RFR: 8323634: Shenandoah: Document behavior of EvacOOM protocol [v3]

[Kelvin Nilsen]

On Fri, 12 Jan 2024 22:25:31 GMT, William Kemper <wkemper at openjdk.org> wrote:

>> Kelvin Nilsen has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Initialize evacuation state
>
> src/hotspot/share/gc/shenandoah/shenandoahEvacOOMHandler.cpp line 208:
> 
>> 206: //  3. The count of threads authorized to evacuate for allocation has been decremented, because this thread is no
>> 207: //     longer authorized.
>> 208: //  4. We have waited for all evacuating threads to stop allocating, after which it is safe for this thread to resolve
> 
> This is where I think the implementation breaks down. If thread `A` is the _first_ thread to attempt evacuation and it fails _before_ any other thread has attempted to evacuate, then thread `A` "believes" that no other threads are evacuating and it returns immediately. How does the protocol then prevent other threads from proceeding with evacuation.

Even when thread A is the first thread to attempt evacuation, it will:
1. Iterate through all counters and set the OOM bit on each one.  Any new thread that attempts to enter_evacuation() will check the OOM bit on its respective counter.  If the OOM bit is already set, that new thread will not be authorized to allocate.  If the thread happens to enter before this thread A has set its OOM bit, then we resolve this in the next step.
2. After setting the OOM bit on each counter, we wait_for_no_evac_threads before we consider it safe to make use of a from-space pointer.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17385#discussion_r1454055307