1 /*
2 * Copyright 2021 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.buffer.api;
17
18 import io.netty5.util.Resource;
19 import io.netty5.util.Send;
20
21 /**
22 * This interface encapsulates the ownership of a {@link Resource}, and exposes a method that may be used to transfer
23 * this ownership to the specified recipient thread.
24 *
25 * @param <T> The concrete type of {@link Resource} that is owned.
26 */
27 @SuppressWarnings("InterfaceMayBeAnnotatedFunctional")
28 public interface Owned<T> {
29 /**
30 * Transfer the ownership of the resource, to the calling thread. The resource instance is invalidated but without
31 * disposing of its internal state. Then a new resource instance with the given owner is produced in its stead.
32 * <p>
33 * This method is called by {@link Send} implementations. These implementations will ensure that the transfer of
34 * ownership (the calling of this method) happens-before the new owner begins accessing the new object. This ensures
35 * that the new resource instance is safely published to the new owners.
36 *
37 * @param drop The drop object that knows how to dispose of the state represented by this {@link Resource}.
38 * @return A new resource instance that is exactly the same as this resource.
39 */
40 T transferOwnership(Drop<T> drop);
41 }