At <> you will find a portable ooRexx debug version for Windows that includes a test version of the suggested multithreaded trace, implemented in a way that adheres to Rick's idea, such that a Rexx programmer can freely format traces as he or she wishes.

The above web site includes Rexx test scripts that are only meant to demonstrate and test the current implemtation.

The readme.txt file includes suggested drafts and is copied to this message at 
the end.

Please post any feedback, findings, bugs here.



   Multithreaded tracing, TraceObject class

   This readme.txt file accompanies a portable Windows version of ooRexx 5.1beta
   that implements multithreaded trace prefixes and makes it possible to create
   one own's trace line renderings as well as to use the infrastructure for
   profiling (analyzing) the execution of Rexx programs.

   - unzip the ooRexx portable version, go into the directory and run
      "setupoorexx.cmd" which creates batch files, e.g.:

      - setenv2rxenv.cmd ... run to change PATH to first point to the
                             portable version of ooRexx; run Rexx programs
                             with "rexx myProgram.rex" such that the
                             operating system looks and finds for rexx.exe

   - there are three test Rexx programs (you can use your own Rexx programs):

      - test01.rex ... a simple test Rexx program

      - test02.rex ... a multithreaded test Rexx program to test guarded and
                       unguarded method routines

      - test03.rex ... this is test01.rex with an intenional syntax error at the

   - there are three Rexx programs that exploit the new infrastructure:

      - p1_traceRunner.rex ... executes the Rexx program (name supplied via the
                               command line argument) four times, once with
                               .TraceObject~option set to 'N' (normal),
                               'S' (standard), 'F' (full), 'P' (profiling mode);
                               each run will have the generated TraceObjects
                               collected in an array that could be used to 
                               the runs afterwards

      - p2_traceInterceptor.rex ... like p1_traceRunner.rex in addition:
                               demonstrates how to intercept each TraceObject

      - p3_traceEditingPrefix.rex ... like p2_traceInterceptor.rex in addition:
                               demonstrates how to change the trace line

   To use the infrastructure:

       - unzip the portable ooRexx version, run setupoorexx.cmd, then the 
         script setenv2rxenv.cmd and remain in that session to run the above
         programs (PATH got set in it), e.g.

            rexx p1_traceRunner.rex        test01.rex (or any other Rexx 
            rexx p2_traceInterceptor.rex   test02.rex (or any other Rexx 
            rexx p3_traceEditingPrefix.rex test03.rex (or any other Rexx 

   Please note: the test programs are artificial and got created to test and
   demonstrate the infrastructure.


   What follows are drafts for rexxref.pdf.


   Starting out with the current documentation the nomenclatura is kept the 
   possibly with additional information meant for the debugging section in

   --- draft (rexxref.pdf) - begin ---

        15.4 Debugging Multithreaded Programs

        ooRexx allows for executing different parts of ooRexx programs on 
        threads of execution using different Rexx interpreter within a single
        operating system process.  This makes it difficult and at times even
        impossible to debug such multithreaded programs without any additional
        information about the specific execution context.  Relevant information
        for debugging multithreaded programs may be: the Rexx interpreter 
        that executes an invocation ("activation") running on which operating
        system thread and whether a lock is held for exclusive access of an
        object's attribute ("object variable") pool.

        To ease debugging of multithreaded programs the execution context can be
        indicated with a "multithreaded trace prefix" ("OPTION") string in the
        following form "[R1 T1 I5 G A1 L2 *]", where

          - "R1": "R" stands for Rexx interpreter instance and the number (a
             counter) indicates which of the instances executes the current
             invocation (activation).

          - "T1": "T" stands for (operating system) thread and the number (a
             counter) indicates on which of the currently existing threads the
             activity gets executed

          - "I5": "I" stands for invocation (activation) and the number (a 
              indicates which invocation gets executed on that thread (activity)

        Information in the OPTION if currently tracing statements of method
        routines (otherwise the remainder of the prefix will be blank):

          - "G" or "U": this character indicates whether the method routine is
             defined to be guarded or unguarded.

          - "A1" : "A" stands for "attribute pool" ("object variable 
            and the number (a counter) indicates which object variable 
            gets used in this invocation of the method routine.  Each object 
            have its own attribute pool which can be directly accessed by method
            routines of the same scope, i.e.  method routines that are defined 
            the same class from which the object got created.  Therefore the A
            indicator will refer to the same object if the number is the same.

          - "L2": "L" stands for object lock count and the number (a counter)
            indicates how many object lock reservations have taken place at that
            point in time. Whenever another method routine of the same scope 
            invoked the object lock count increases by one, upon return the 
            lock count decreases by one.

          - "*" or " ": the asterisk indicates that the activity holds the 
            lock. Guarded methods are blocked, if they do not hold the object 
            Methods in the unguarded state will never block.


          - the GUARD keyword instruction can be used within a method routine to
            change the state from guarded (synchronize on the object lock) to
            unguarded (ignore the object lock) using unconditionally the keyword
            statement GUARD OFF and vice versa (using unconditionally the 
            statement GUARD ON),

          - the keyword instructions "GUARD ON someAttribute=someValue" and 
            OFF someAttribute=someValue" allow changing the state of the method
            routine to guarded or to unguarded depending on the value of an 
            attribute "someAttribute" which needs to get changed in another
            concurrently running method routine of the same (class) scope. Such
            attributes are known to be used as "control variables" to 
            activities on different threads,

          - if you wish to directly change the value of any exposed attribute 
            make sure that the changes take place in the guarded state to 
            concurrent updates from other threads to inhibit inconsistent 

          - the object variable dictionary number represents a specific object,

          - methods in the guarded state that do not possess the trailing 
            are blocked, they are waiting for the object lock,

          - methods in the unguarded state get never blocked,

          - the standard layout of the OPTION is intentionally designed to make
            parsing easy such that analyzing the trace 3output of complex
            multithreaded ooRexx programs becomes easy.

        Starting with ooRexx 5.1 each traced line will be represented with an
        instance of the class TraceObject. Its class attribute OPTION (see the
        documentation of the class TraceObject) is set to N (normal) by default.
        If one needs additional, multithreaded trace information prefixed
        then changing the class attribute OPTION to S (standard) or
        to F (full, for complex multithreaded programs) prepends it to each
        traced line. Each TraceObject will be sent as argument to the LINEOUT
        message to the .traceOutput monitor object.

        This makes it possible to intercept these trace LINEOUT messages with
        the TraceObject argument by adding one own's Rexx object as a 
        object which implements the LINEOUT method (if doing so, one should
        also implement the UNKNOWN method to forward all unknown messages).

   --- draft (rexxref.pdf) - end ---

   --- draft for class TraceObject (rexxref.pdf) - begin ---

   5.3.x TraceObject Class

   A TraceObject is a subclass of StringTable and therefore is a MapCollection
   using unique character string indexes.  The items of a StringTable can be any
   valid Rexx object.  See also Directory Class, a MapCollection similar to
   StringTable, but with additional methods setMethod and unsetMethod.

   The trace infrastructure of ooRexx will create an instance for each trace 
   and store the following information with the following indexes:

        Index               Item

        "ATTRIBUTEPOOL"     a number, makeString prepends it with the letter A
        "HASOBJECTLOCK"     .true/.false, makeString uses an asterisk, if .true,
                            a blank character else
        "INTERPRETER"       a number, makeString prepends it with the letter R
        "INVOCATION"        a number, makeString prepends it with the letter I
        "ISGUARDED"         .true/.false, makeString uses the letter G, if 
                            the letter U else
        "OBJECTLOCKCOUNT"   a number, makeString prepends it with the letter L
        "OPTION"            the option at creation time, e.g. N or S
        "THREAD"            a number, makeString prepends it with the letter T
        "TIMESTAMP"         the creation .DateTime
        "TRACELINE"         the trace line string

   The section "15.4 Debugging Multithreaded Programs" gives more information
   about debugging multithreaded programs.

   r.3.x.1. collector (Class Attribute)

   This attribute controls whether created TraceObjects get collected or not.
   If its value is set to .nil (default) then the created TraceObjects are not
   collected. This attribute can be set to anything else, if the object can
   understand the APPEND message, which is the case for all OrderedCollections
   like Array.

   r.3.x.2. option (Class Attribute)

   This attribute controls whether a traced line gets displayed and how
   makeString renders the traced line. The following values are defined for this

            N       "normal", the trace line gets displayed without any
                    multithreaded prefix information

            S       "standard", the trace line gets prefixed with a
                    bracketed string that indicates the thread and the
                    invocation number, e.g. "[T1   I2  ]" or if a method
                    routine gets traced in addition whether it was defined
                    guarded or ungaurded, the object lock count and whether
                    the object lock is reserved (indicated by an asterisk),
                    e.g. "[T1   I9   G L1   *] "

            F       "full", the trace line with a bracketed string that adds
                    the Rexx instance and the activity pool number, e.g.
                    "[R1   T1   I15 ]" or if a method routine gets traced adds
                    the attribute pool number, e.g. "R1   T4   I19  G A3   L1

            P       "profiling", no trace line will be shown, yet, each created
                    TraceObject will get appended to the class attribute 
                    if not .nil. This allows analyzing the execution of traced
                    Rexx programs for many purposes.

   r.3.x.3. compareTo

   Implements the default sort order using the value of the TIMESTAMP entry.

   r.3.x.4. init

   The constructor adds the TIMESTAMP and OPTION entries for later analysis.

   r.3.x.5. makeString

   This method formats the traceline according to the current setting of the
   class attribute OPTION:

            N or P          normal trace line
            S               standard prefix prepended to trace line
            F               full prefix prepended to trace line

   For more information see class attribute OPTION and section "15.4 Debugging
   Multithreaded Programs".

   --- draft for class TraceObject (rexxref.pdf) - end   ---

   If there are questions, comments please use the ooRexx developer list on
   sourceforge (

   2024-01-28, rgf

Oorexx-devel mailing list

Reply via email to