Annotation Type DMethodOptions


@Retention(SOURCE) @Target(METHOD) public @interface DMethodOptions
Options for dynamic methods. A method annotated with a DynamicMethod annotation may also be annotated with a DMethodOptions annotation. This annotation set various options that affect performance.
  • Element Details

    • lockingMode

      Set the type of locking used by the helper class. Locking protects data structures used when a dynamic method is run and when a dynamic method's class (and that class' subclasses) are loaded. Java loads classes immediately before those classes are used. Values are
      • DMethodOptions.Locking.NONE (no locking)
      • DMethodOptions.Locking.DEFAULT (use the default, typically DMethodOptions.Locking.MUTEX)
      • DMethodOptions.Locking.MUTEX (use a mutual-exclusion lock)
      • DMethodOptions.Locking.RWLOCK (use a read-write lock)

      The option DMethodOptions.Locking.DEFAULT picks a system-wide default (DMethodOptions.Locking.MUTEX, unless overridden by compiler flags). The option DMethodOptions.Locking.NONE should be used when all uses of a dynamic method, including loading the method's class and any subclass that implements the dynamic method, are single threaded. The option DMethodOptions.Locking.MUTEX (the default) is best in nearly all cases where locking is needed. The option DMethodOptions.Locking.RWLOCK reduces lock contention in multithreaded applications when a very large number of threads may call the same method concurrently. The lock is held only during method searching and cache-maintenance operations, so the time a method executes is not relevant. One should not, however, that method search time grows with both the complexity of the class hierarchy and with the number of arguments searched.

      With a trivial dynamic method that has a single argument, a read-write lock will account for about half of the execution time while a mutex will account for about a quarter of the execution time when there is no lock contention.

      To set the default option for the compiler, the option name is org.bzdev.lang.DMethodOption.lockingMode and the legal values are NONE, MUTEX, and RWLOCK. For example, to turn off locking as the default with javac, use

      
          javac -Aorg.bzdev.lang.DMethodOptions.lockingMode=NONE ...  FILE.java
       
      Returns:
      the value of this element
      Default:
      MUTEX
    • traceMode

      boolean traceMode
      Set whether or not to trace a method search. A value of true indicates that a trace of the search for an appropriate set of arguments and implementing class should be printed on standard output when the dynamic method annotated with this annotation is used; false if no tracing should be done. The default is false.

      This should only be set to true for debugging.

      Returns:
      the value of this element
      Default:
      false
    • limitFactor

      int limitFactor
      Provides a scale factor so that the cache size for a helper will be the scale factor multiplied by the value of DMethodParameters.getDefaultCacheLimit(). When a search for the appropriate method is needed, the the search results will be cached for later use. The cache has a finite size. This option is intended for cases where one expects that the default value will result in an inappropriate cache size for a specific dynamic method. The method DMethodParameters.getDefaultCacheLimit(int) should be used to change the cache size for all dynamic methods. The values should be changed from the default ones only if performance measurements or tracing show that there is a good reason to do that.
      Returns:
      the value of this element
      Default:
      1