Package 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 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
  Description
  `static enum`
  `RexxCleanupRef.RefKind`
  Defines the valid kinds of Rexx related resources to finalize.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final IdentityHashMap<RexxCleanupRef,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 final 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
  Description
  `RexxCleanupRef(Object referent, RexxCleanupRef.RefKind refKind, Object obj_id)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  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 String`
  `getStatistics()`
  Creates a string with formatted instances, finalizes and not yet finalized objects grouped by
  `static String`
  `getStatistics(String title)`
  Creates a string with formatted instances, finalizes and not yet finalized objects grouped by
  `protected int`
  `jniRexxTerminateInterpreterInstance(String rii_ID)`
  `protected int`
  `jniUnregisterRexxObject(String obj_ID)`
  Unregisters the Rexx object denoted by 'obj_ID' from the JNI registry.
  `static void`
  `main(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, reachabilityFence, refersTo`

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

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

- ## Field Details

  - ### version

    public static final 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 IdentityHashMap<RexxCleanupRef,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 Details

  - ### RexxCleanupRef

    public RexxCleanupRef(Object referent, RexxCleanupRef.RefKind refKind, 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 Details

  - ### 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(String rii_ID)

  - ### jniUnregisterRexxObject

    protected int jniUnregisterRexxObject(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(String[] args)

  - ### getStatistics

    public static String getStatistics()
    Creates a string with formatted instances, finalizes and not yet finalized objects grouped by

  - ### getStatistics

    public static String getStatistics(String title)
    Creates a string with formatted instances, finalizes and not yet finalized objects grouped by