org.rexxla.bsf.engines.rexx

## Class RexxCleanupRef

- java.lang.Object
- - java.lang.ref.Reference<T>
  - - java.lang.ref.PhantomReference
    - - org.rexxla.bsf.engines.rexx.RexxCleanupRef

-     public class RexxCleanupRef
      extends java.lang.ref.PhantomReference

  With Java 9 Object.finalize() gets deprecated, therefore we use `PhantomReferences` for cleanup actions in these two cases:
  1. RexxAndJava.java: when the RexxEngine gets terminated we make sure that the peer RexxInterpreter gets terminated and removed from the list of available RexxInterpreter instances.
  2. RexxProxy.java: whenever a RexxProxy object gets out of scope its reference count needs to be decreased such that eventually ooRexx can claim the peer Rexx object.

  To not block termination of Rexx the cleanup thread does not use the blocking `remove()` method on the reference queue, but rather `remove(timeout)` and terminates when the queue is empty. To make sure that the cleanup gets carried out eventually, each time a new instance of this class gets created the @link{RexxCleanupRef#startCleanerThread()} method gets invoked, if it is not running. From time to time the static method @link{RexxCleanupRef#startCleanerThread()} gets invoked by BSF4ooRexx directly in the `RexxAndJava` class.

      ------------------------ Apache Version 2.0 license -------------------------
          Copyright (C) 2021-2022 Rony G. Flatscher

          Licensed 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

              http://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.
       -----------------------------------------------------------------------------

  Version:
    100.20220802
  Author:
    Rony G. Flatscher

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RexxCleanupRef.RefKind` Defines the valid kinds of Rexx related resources to finalize.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.IdentityHashMap<RexxCleanupRef,java.lang.Object>` | `pinnedReferences` Learned that `PhantomReferences` must be refenced themselves otherwise they may never be put on the reference queue, so storing them in this `IdentityHashMap` until the reference is being put on the reference queue for processing, at which time the reference will be removed from the `IdentityHashMap`.
    `static java.lang.String` | `version` Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RexxCleanupRef(java.lang.Object referent, RexxCleanupRef.RefKind refKind, java.lang.Object obj_id)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `getCleanInvocationCounter()` Getter method.
    `static long[][]` | `getCounters()` Getter that returns a clone (copy) of the current counters array indexed by ordinal value of `RefKind` in first dimension, and by 0 (created instances) and 1 (finalizers ran).
    `static boolean` | `getDebugRexxProxy()` Getter for `bDebugRexxProxy`.
    `static boolean` | `getDebugRII()` Returns the current setting of the private boolean field bDebugRII which controls debug output in the context of terminating a Rexx interpreter instance (RII).
    `static int` | `getGcThreshold()` Threshold of unfinalized RexxEngines which will cause a System.gc() to be called.
    `static int` | `getGcThresholdMax()` Return gcThresholdMax attribute.
    `static int` | `getGcThresholdMin()` Return gcThresholdMin attribute.
    `static RexxCleanupRef.RefKind[]` | `getRefkinds()` Getter that returns a clone (copy) of the enum constants of the @link{RefKind} enum class.
    `static java.lang.String` | `getStatistics()` Creates a string with formatted instances, finalizes and not yet finalized objects grouped by
    `static java.lang.String` | `getStatistics(java.lang.String title)` Creates a string with formatted instances, finalizes and not yet finalized objects grouped by
    `protected int` | `jniRexxTerminateInterpreterInstance(java.lang.String rii_ID)`
    `protected int` | `jniUnregisterRexxObject(java.lang.String obj_ID)` Unregisters the Rexx object denoted by 'obj_ID' from the JNI registry.
    `static void` | `main(java.lang.String[] args)`
    `static void` | `setDebugRexxProxy(boolean newDebugState)` Setter for `bDebugRexxProxy`.
    `static void` | `setDebugRII(boolean newDebugState)` Allows changing Setter for `bDebugRII` (Rexx interpreter instance related).
    `static void` | `setGcThreshold(int newValue)` Set threshold of unfinalized RexxEngines which will cause a System.gc() to be called.
    `static void` | `setGcThresholdMax(int newValue)` Set gcThresholdMin attribute: `newValue>=gcThresholdMin`.
    `static void` | `setGcThresholdMin(int newValue)` Set gcThresholdMin attribute: `newValue>=1 && newValue<=gcThresholdMax`.

    - ### Methods inherited from class java.lang.ref.PhantomReference

      `get`

    - ### Methods inherited from class java.lang.ref.Reference

      `clear, clone, enqueue, isEnqueued`

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

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

- - ### Field Detail

    - #### version

          public static final java.lang.String version

      Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.
      See Also:
        Constant Field Values

    - #### pinnedReferences

          public static final java.util.IdentityHashMap<RexxCleanupRef,java.lang.Object> pinnedReferences

      Learned that `PhantomReferences` must be refenced themselves otherwise they may never be put on the reference queue, so storing them in this `IdentityHashMap` until the reference is being put on the reference queue for processing, at which time the reference will be removed from the `IdentityHashMap`. The `IdentityHashMap` gets used as `IdentityHashSet`, i.e. the value part will always be null.

  - ### Constructor Detail

    - #### RexxCleanupRef

          public RexxCleanupRef(java.lang.Object referent,
                                RexxCleanupRef.RefKind refKind,
                                java.lang.Object obj_id)

      Constructor. Whenever an instance gets created the static method @link{#clean} gets invoked to make sure that that the reference queue gets processed from time to time.
      Parameters:
        `referent` - the RexxEngine or RexxProxy object to watch
        `refKind` - RexxCleanupRef.
        `obj_id` - the string id maintained in native code or RexxEngine of finalized RexxScriptEngine or the RexxEngine instance peer of the RexxScriptEngine instance

  - ### Method Detail

    - #### getDebugRII

          public static boolean getDebugRII()

      Returns the current setting of the private boolean field bDebugRII which controls debug output in the context of terminating a Rexx interpreter instance (RII).
      Returns:
        returns current setting (if `true` then showing debug message when terminating Rexx interpreter instance)

    - #### setDebugRII

          public static void setDebugRII(boolean newDebugState)

      Allows changing Setter for `bDebugRII` (Rexx interpreter instance related).
      Parameters:
        `newDebugState` - if `true` then showing a debug message when terminating a Rexx interpreter instance

    - #### getDebugRexxProxy

          public static boolean getDebugRexxProxy()

      Getter for `bDebugRexxProxy`.
      Returns:
        returns current setting (if `true` then showing debug message when dereferencing a RexxProxy)

    - #### setDebugRexxProxy

          public static void setDebugRexxProxy(boolean newDebugState)

      Setter for `bDebugRexxProxy`.
      Parameters:
        `newDebugState` - if `true` then showing a debug message when dereferencing a RexxProxy

    - #### getCleanInvocationCounter

          public static int getCleanInvocationCounter()

      Getter method.
      Returns:
        current number of clean threads started so far (depends on the implementation)

    - #### getRefkinds

          public static RexxCleanupRef.RefKind[] getRefkinds()

      Getter that returns a clone (copy) of the enum constants of the @link{RefKind} enum class.
      Returns:
        array of enum constants

    - #### getCounters

          public static long[][] getCounters()

      Getter that returns a clone (copy) of the current counters array indexed by ordinal value of `RefKind` in first dimension, and by 0 (created instances) and 1 (finalizers ran).
      Returns:
        copy of array at time of invocation

    - #### getGcThresholdMin

          public static int getGcThresholdMin()

      Return gcThresholdMin attribute.
      Returns:
        gcThresholdMin value

    - #### setGcThresholdMin

          public static void setGcThresholdMin(int newValue)

      Set gcThresholdMin attribute: `newValue>=1 && newValue<=gcThresholdMax`.
      Parameters:
        `newValue` -

    - #### getGcThresholdMax

          public static int getGcThresholdMax()

      Return gcThresholdMax attribute.
      Returns:
        gcThresholdMax value

    - #### setGcThresholdMax

          public static void setGcThresholdMax(int newValue)

      Set gcThresholdMin attribute: `newValue>=gcThresholdMin`.
      Parameters:
        `newValue` -

    - #### getGcThreshold

          public static int getGcThreshold()

      Threshold of unfinalized RexxEngines which will cause a System.gc() to be called.
      Returns:
        current threshold value that triggers System.gc()

    - #### setGcThreshold

          public static void setGcThreshold(int newValue)

      Set threshold of unfinalized RexxEngines which will cause a System.gc() to be called.
      Parameters:
        `newValue` - number of unfinalized RexxEngines that will cause an out of bound System.gc() to be triggered (to reclaim unused BSF4ooRexx resources)

    - #### jniRexxTerminateInterpreterInstance

          protected int jniRexxTerminateInterpreterInstance(java.lang.String rii_ID)

    - #### jniUnregisterRexxObject

          protected int jniUnregisterRexxObject(java.lang.String obj_ID)

      Unregisters the Rexx object denoted by 'obj_ID' from the JNI registry.
      Parameters:
        `obj_ID` - the object id that is used as a key on the JNI side
      Returns:
        number of references to the Rexx object in the JNI registry left; a number of '0' indicates that no references are left, a return value of '-1' indicates that the Rexx object was not registered (could not be found)

    - #### main

          public static void main(java.lang.String[] args)

    - #### getStatistics

          public static java.lang.String getStatistics()

      Creates a string with formatted instances, finalizes and not yet finalized objects grouped by
      Returns:
        formatted String (including newline at the end of each line)

    - #### getStatistics

          public static java.lang.String getStatistics(java.lang.String title)

      Creates a string with formatted instances, finalizes and not yet finalized objects grouped by
      Parameters:
        `title` - to be included in the header line at the top
      Returns:
        formatted String (including newline at the end of each line)