1b65bf9a23
Motivation: This makes it possible to use the new buffer API in Netty as is. Modification: Make the MemSegBuffer implementation class implement AsByteBuf and ReferenceCounted. The produced ByteBuf instance delegates all calls to the underlying Buffer instance as faithfully as possible. One area where the two deviates, is that it's not possible to create non-retained duplicates and slices with the new buffer API. Result: It is now possible to use the new buffer API on both client and server side. The Echo* examples demonstrate this, and the EchoIT proves it with a test. The API is used more directly on the client side, since the server-side allocator in Netty does not know how to allocate buffers with the incubating API.
100 lines
3.8 KiB
Java
100 lines
3.8 KiB
Java
/*
|
|
* Copyright 2020 The Netty Project
|
|
*
|
|
* The Netty Project licenses this file to you under the Apache License,
|
|
* version 2.0 (the "License"); you may not use this file except in compliance
|
|
* with the License. You may obtain a copy of the License at:
|
|
*
|
|
* https://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
* License for the specific language governing permissions and limitations
|
|
* under the License.
|
|
*/
|
|
package io.netty.buffer.api;
|
|
|
|
/**
|
|
* An Rc is a reference counted, thread-confined, resource of sorts. Because these resources are thread-confined, the
|
|
* reference counting is NOT atomic. An Rc can only be accessed by one thread at a time - the owner thread that the
|
|
* resource is confined to.
|
|
* <p>
|
|
* When the last reference is closed (accounted for using {@link AutoCloseable} and try-with-resources statements,
|
|
* ideally), then the resource is desposed of, or released, or returned to the pool it came from. The precise action is
|
|
* implemented by the {@link Drop} instance given as an argument to the Rc constructor.
|
|
*
|
|
* @param <I> The concrete subtype.
|
|
*/
|
|
public interface Rc<I extends Rc<I>> extends AutoCloseable, Deref<I> {
|
|
/**
|
|
* Increment the reference count.
|
|
* <p>
|
|
* Note, this method is not thread-safe because reference counted objects are meant to thread-confined.
|
|
*
|
|
* @return This Rc instance.
|
|
*/
|
|
I acquire();
|
|
|
|
@Override
|
|
default I get() {
|
|
return acquire();
|
|
}
|
|
|
|
@Override
|
|
default boolean isInstanceOf(Class<?> cls) {
|
|
return cls.isInstance(this);
|
|
}
|
|
|
|
/**
|
|
* Decrement the reference count, and despose of the resource if the last reference is closed.
|
|
* <p>
|
|
* Note, this method is not thread-safe because reference counted objects are meant to be thread-confined.
|
|
*
|
|
* @throws IllegalStateException If this Rc has already been closed.
|
|
*/
|
|
@Override
|
|
void close();
|
|
|
|
/**
|
|
* Send this reference counted object instance to another Thread, transferring the ownership to the recipient.
|
|
* <p>
|
|
* Note that the object must be {@linkplain #isOwned() owned}, and cannot have any outstanding borrows,
|
|
* when it's being sent.
|
|
* That is, all previous acquires must have been closed, and {@link #isOwned()} must return {@code true}.
|
|
* <p>
|
|
* This instance immediately becomes inaccessible, and all attempts at accessing this reference counted object
|
|
* will throw. Calling {@link #close()} will have no effect, so this method is safe to call within a
|
|
* try-with-resources statement.
|
|
*/
|
|
Send<I> send();
|
|
|
|
/**
|
|
* Check that this reference counted object is owned.
|
|
* <p>
|
|
* To be owned, the object must have no outstanding acquires, and no other implementation defined restrictions.
|
|
*
|
|
* @return {@code true} if this object can be {@linkplain #send() sent},
|
|
* or {@code false} if calling {@link #send()} would throw an exception.
|
|
*/
|
|
boolean isOwned();
|
|
|
|
/**
|
|
* Count the number of borrows of this object.
|
|
* Note that even if the number of borrows is {@code 0}, this object might not be {@linkplain #isOwned() owned}
|
|
* because there could be other restrictions involved in ownership.
|
|
*
|
|
* @return The number of borrows, if any, of this object.
|
|
*/
|
|
int countBorrows();
|
|
|
|
/**
|
|
* Check if this object is accessible.
|
|
*
|
|
* @return {@code true} if this object is still valid and can be accessed,
|
|
* otherwise {@code false} if, for instance, this object has been dropped/deallocated,
|
|
* or been {@linkplain #send() sent} elsewhere.
|
|
*/
|
|
boolean isAccessible();
|
|
}
|