Ref (apache-cassandra API)
Date: 2018-02-12

org.apache.cassandra.utils.concurrent

## Class Ref<T>

- java.lang.Object
- - org.apache.cassandra.utils.concurrent.Ref<T>

- All Implemented Interfaces:
    RefCounted<T>

      public final class Ref<T>
      extends java.lang.Object
      implements RefCounted<T>

  An object that needs ref counting does the two following: - defines a Tidy object that will cleanup once it's gone, (this must retain no references to the object we're tracking (only its resources and how to clean up)) Then, one of two options: 1) Construct a Ref directly pointing to it, and always use this Ref; or 2) - implements RefCounted - encapsulates a Ref, we'll call selfRef, to which it proxies all calls to RefCounted behaviours - users must ensure no references to the selfRef leak, or are retained outside of a method scope. (to ensure the selfRef is collected with the object, so that leaks may be detected and corrected) This class' functionality is achieved by what may look at first glance like a complex web of references, but boils down to: Target --> selfRef --> [Ref.State] <--> Ref.GlobalState --> Tidy ^ | Ref ---------------------------------------- | Global ------------------------------------- So that, if Target is collected, Impl is collected and, hence, so is selfRef. Once ref or selfRef are collected, the paired Ref.State's release method is called, which if it had not already been called will update Ref.GlobalState and log an error. Once the Ref.GlobalState has been completely released, the Tidy method is called and it removes the global reference to itself so it may also be collected.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.cassandra.utils.concurrent.RefCounted

      `RefCounted.Tidy`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG_ENABLED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Ref(T referent, RefCounted.Tidy tidy)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `void` | `ensureReleased()`
    `java.lang.Throwable` | `ensureReleased(java.lang.Throwable accumulate)`
    `T` | `get()`
    `int` | `globalCount()` A convenience method for reporting:
    `java.lang.String` | `printDebugInfo()`
    `Ref<T>` | `ref()`
    `void` | `release()` Must be called exactly once, when the logical operation for which this Ref was created has terminated.
    `Ref<T>` | `tryRef()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEBUG_ENABLED

          public static final boolean DEBUG_ENABLED

  - ### Constructor Detail

    - #### Ref

          public Ref(T referent,
                     RefCounted.Tidy tidy)

  - ### Method Detail

    - #### release

          public void release()

      Must be called exactly once, when the logical operation for which this Ref was created has terminated. Failure to abide by this contract will result in an error (eventually) being reported, assuming a hard reference to the resource it managed is not leaked.

    - #### ensureReleased

          public java.lang.Throwable ensureReleased(java.lang.Throwable accumulate)

    - #### ensureReleased

          public void ensureReleased()

    - #### close

          public void close()

    - #### get

          public T get()

    - #### tryRef

          public Ref<T> tryRef()

      Specified by:
        `tryRef` in interface `RefCounted<T>`
      Returns:
        the a new Ref() to the managed object, incrementing its refcount, or null if it is already released

    - #### ref

          public Ref<T> ref()

      Specified by:
        `ref` in interface `RefCounted<T>`

    - #### printDebugInfo

          public java.lang.String printDebugInfo()

    - #### globalCount

          public int globalCount()

      A convenience method for reporting:
      Returns:
        the number of currently extant references globally, including the shared reference

Copyright © 2018 The Apache Software Foundation