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:

    • 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