Package com.linecorp.armeria.unsafe

Class PooledObjects

java.lang.Object
com.linecorp.armeria.unsafe.PooledObjects
@UnstableApi public final class PooledObjects extends Object
Utility class that provides ways to create a pooled Bytes and manage its life cycle.

Warning: Using a pooled Bytes is very advanced and can open up much more complicated management of a reference counted Bytes. You should only ever do this if you are very comfortable with Netty. It is recommended to also read through Reference counted objects for more information on pooled objects.

What is a pooled Bytes?

A pooled Bytes is a special variant of Bytes whose Bytes.isPooled() returns true. Currently, HttpData is a Bytes and it's usually created via HttpData.wrap(ByteBuf) by wrapping an existing ByteBuf. It can appear when you consume data using the operations such as:

To put it another way, you'll never see a pooled Bytes if you did not use such operations. You can ignore the rest of this section if that's the case.

Any time you receive a pooled Bytes, it will have an underlying ByteBuf that must be released - failure to release the ByteBuf will result in a memory leak and poor performance. You must make sure to do this by calling Bytes.close(), usually in a try-with-resources structure to avoid side effects, e.g. 


 HttpResponse res = client.get("/");
 res.aggregate(AggregationOptions.usePooledObjects(ctx.alloc(), ctx.executor()))
    .thenApply(aggResp -> {
        // try-with-resources here ensures the content is released
        // if it is a pooled HttpData, or otherwise it's no-op.
        try (HttpData content = aggResp.content()) {
            if (!aggResp.status().equals(HttpStatus.OK)) {
                throw new IllegalStateException("Bad response");
            }
            try {
                return OBJECT_MAPPER.readValue(content.toInputStream(), Foo.class);
            } catch (IOException e) {
                throw new IllegalArgumentException("Bad JSON: " + content.toStringUtf8());
            }
        }
    });

In the above example, it is the initial try (HttpData content = ...) that ensures the data is released. Calls to methods on HttpData will all work and can be called any number of times within this block. If called after the block or a manual call to Bytes.close(), these methods will fail or corrupt data.

  • Method Details

    • close

      public static void close(Object obj)
      Closes the given pooled Bytes. Does nothing if it's not a pooled Bytes.
      Parameters:
      obj - maybe an Bytes to close

    • touch

      public static <T> T touch(T obj)
      Calls ByteBuf.touch(Object) on the specified Bytes' underlying ByteBuf. Uses the specified Bytes as a hint. Does nothing if it's not a pooled Bytes.
      Parameters:
      obj - maybe a pooled Bytes to touch its underlying ByteBuf

    • touch

      public static <T> T touch(T obj, @Nullable @Nullable Object hint)
      Calls ByteBuf.touch(Object) on the specified Bytes's underlying ByteBuf. Does nothing if it's not a pooled Bytes.
      Parameters:
      obj - maybe a pooled Bytes to touch its underlying ByteBuf
      hint - the hint to specify when calling ByteBuf.touch(Object)

    • copyAndClose

      public static <T> T copyAndClose(T obj)
      Creates an unpooled copy of the given HttpData and closes the given HttpData. Returns the given object as is if it's not a pooled HttpData. This method is useful when you need to pass your pooled HttpData instances to the third party who is not capable of handling pooled HttpData.
      Parameters:
      obj - maybe an HttpData to copy