1 /*
2 * Copyright 2012 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.util;
17
18 /**
19 * An attribute which allows to store a value reference. It may be updated atomically and so is thread-safe.
20 *
21 * @param <T> the type of the value it holds.
22 */
23 public interface Attribute<T> {
24
25 /**
26 * Returns the key of this attribute.
27 */
28 AttributeKey<T> key();
29
30 /**
31 * Returns the current value, which may be {@code null}
32 */
33 T get();
34
35 /**
36 * Sets the value
37 */
38 void set(T value);
39
40 /**
41 * Atomically sets to the given value and returns the old value which may be {@code null} if non was set before.
42 */
43 T getAndSet(T value);
44
45 /**
46 * Atomically sets to the given value if this {@link Attribute}'s value is {@code null}.
47 * If it was not possible to set the value as it contains a value it will just return the current value.
48 */
49 T setIfAbsent(T value);
50
51 /**
52 * Removes this attribute from the {@link AttributeMap} and returns the old value. Subsequent {@link #get()}
53 * calls will return {@code null}.
54 *
55 * If you only want to return the old value and clear the {@link Attribute} while still keep it in the
56 * {@link AttributeMap} use {@link #getAndSet(Object)} with a value of {@code null}.
57 *
58 * <p>
59 * Be aware that even if you call this method another thread that has obtained a reference to this {@link Attribute}
60 * via {@link AttributeMap#attr(AttributeKey)} will still operate on the same instance. That said if now another
61 * thread or even the same thread later will call {@link AttributeMap#attr(AttributeKey)} again, a new
62 * {@link Attribute} instance is created and so is not the same as the previous one that was removed. Because of
63 * this special caution should be taken when you call {@link #remove()} or {@link #getAndRemove()}.
64 *
65 * @deprecated please consider using {@link #getAndSet(Object)} (with value of {@code null}).
66 */
67 @Deprecated
68 T getAndRemove();
69
70 /**
71 * Atomically sets the value to the given updated value if the current value == the expected value.
72 * If it the set was successful it returns {@code true} otherwise {@code false}.
73 */
74 boolean compareAndSet(T oldValue, T newValue);
75
76 /**
77 * Removes this attribute from the {@link AttributeMap}. Subsequent {@link #get()} calls will return @{code null}.
78 *
79 * If you only want to remove the value and clear the {@link Attribute} while still keep it in
80 * {@link AttributeMap} use {@link #set(Object)} with a value of {@code null}.
81 *
82 * <p>
83 * Be aware that even if you call this method another thread that has obtained a reference to this {@link Attribute}
84 * via {@link AttributeMap#attr(AttributeKey)} will still operate on the same instance. That said if now another
85 * thread or even the same thread later will call {@link AttributeMap#attr(AttributeKey)} again, a new
86 * {@link Attribute} instance is created and so is not the same as the previous one that was removed. Because of
87 * this special caution should be taken when you call {@link #remove()} or {@link #getAndRemove()}.
88 *
89 * @deprecated please consider using {@link #set(Object)} (with value of {@code null}).
90 */
91 @Deprecated
92 void remove();
93 }