Document semantics for resource locks with `@BeforeEach`/`@AfterEach` lifecycle methods

[sbrannen]

Discussed in #3666

^{Originally posted by Fanael January 30, 2024}
Suppose we have the following:

class ExampleTest {
    @BeforeEach
    void before() {
    }

    @AfterEach
    void after() {
    }

    @ResourceLock("example")
    @Test
    void test() {
    }
}

What, exactly, are the guaranteed semantics of acquisition and release of the example resource lock when the before and after methods are invoked for test? Is it:

• acquired once, held across the three methods, then released?
• acquired before calling each of the three method and released after each return?
• only acquired for the duration of test, potentially allowing the code in before and after to race?
• completely unspecified, so nobody should rely on any particular behavior?

The SharedResourcesDemo example from the guide seems to indicate the first interpretation is correct, because I think it's possible to show it having undesired behavior under other interpretations, but I'd rather be 100% sure.