Module io.netty5.buffer
Package io.netty5.buffer.api.internal

Class LifecycleTracer

  • @UnstableApi
public abstract class LifecycleTracer
extends Object
    Instances of this class record life cycle events of resources, to help debug life-cycle errors.

    • Constructor Detail

      • LifecycleTracer

        public LifecycleTracer()

    • Method Detail

      • get

        public static LifecycleTracer get()
        Get a tracer for a newly allocated resource.

        Note: this call is itself not traced. Instead, it is customary to immediately call allocate() on the returned tracer.

        Returns:
        A new tracer for a resource.

      • allocate

        public abstract void allocate()
        Add to the trace log that the object has been allocated.

      • acquire

        public abstract void acquire​(int acquires)
        Add to the trace log that the object has been acquired, in other words the reference count has been incremented.
        Parameters:
        acquires - The new current number of acquires on the traced object.

      • drop

        public abstract void drop​(int acquires)
        Add to the trace log that the object has been dropped.
        Parameters:
        acquires - The new current number of acquires on the traced object.

      • close

        public abstract void close​(int acquires)
        Add to the trace log that the object has been closed, in other words, the reference count has been decremented.
        Parameters:
        acquires - The new current number of acquires on the traced object.

      • touch

        public abstract void touch​(Object hint)
        Add the hint object to the trace log. The hint objects can be inspected later if a lifecycle related exception is thrown, or if the object leaks.
        Parameters:
        hint - The hint object to attach to the trace log.

      • send

        public abstract <I extends Resource<I>,​T extends ResourceSupport<I,​T>> Owned<T> send​(Owned<T> instance)
        Add to the trace log that the object is being sent.
        Type Parameters:
        I - The resource interface for the object.
        T - The concrete type of the object.
        Parameters:
        instance - The owned instance being sent.
        Returns:
        An Owned instance that may trace the reception of the object.

      • splitTo

        public abstract void splitTo​(LifecycleTracer splitTracer)
        Attach a trace to both life-cycles, that a single life-cycle has been split into two. Such branches happen when two views are created to share a single underlying resource. The most prominent example of this is the Buffer.split() method, where a buffer is broken into two that each covers a non-overlapping region of the original memory. This method is called on the originating, or "parent" tracer, while the newly allocated "child" is given as an argument.
        Parameters:
        splitTracer - The tracer for the life-cycle that was branched from the life-cycle represented by this tracer.

      • attachTrace

        public abstract <E extends Throwable> E attachTrace​(E throwable)
        Attach a life cycle trace log to the given exception.
        Type Parameters:
        E - The concrete exception type.
        Parameters:
        throwable - The exception that will receive the trace log in the form of suppressed exceptions.
        Returns:
        The same exception instance, that can then be thrown.

      • collectTraces

        public abstract Collection<LeakInfo.TracePoint> collectTraces()
        Return the life-cycle trace as an ordered Collection of LeakInfo.TracePoints. The trace points are ordered chronologically in the collection, with earlier events before later ones. The returned collection is not modifiable.
        Returns:
        A collection of trace points.