15.4.2. Multithreaded Additions to TRACE

To ease debugging of multithreaded programs the execution context will be displayed with a "multithreaded trace prefix string" in square brackets (see also the class method makeStringImpl and the class attribute "option" of the "TraceObject class) in the following form, if the class attribute option is set to "F" (full):

"[R1 T2 I3 Gu A4 L5 *W]", where

"R1": "R" stands for Rexx interpreter instance and the number (a counter) indicates which of the instances executes the current invocation (activation).
"T2": "T" stands for (operating system) thread and the number (a counter) indicates on which of the currently existing threads the activity gets executed.
"I3": "I" stands for invocation (activation) and the number (a counter) indicates which invocation gets executed on that thread (activity).

If currently tracing methods then in addition the following information gets displayed:

"G" or "U": this character indicates whether the method is defined to be guarded or unguarded (see Guarded Methods in chapter GUARD).
"g", "u" or " " (blank character): this character indicates whether the method is currently executing in a state that is opposite of the method's definition, i.e., g for an unguarded method that is currently guarded, or, u for a guarded method that is currently unguarded, or blank else (see Guarded Methods in chapter GUARD).
"A4": "A" stands for "attribute pool" (also known as "object variable dictionary") and the number (a counter) indicates which object variable dictionary of which scope gets used in this invocation of the method. Each object will have its own attribute pool which can be directly accessed by methods of the same scope. Therefore the A indicator will refer to the same object and the same scope if the number is the same.
"L5": "L" stands for scope lock count and the number (a counter) indicates how many object scope lock reservations have taken place at that point in time. Whenever another guarded method of the same scope gets invoked the object's scope lock count increases by one, upon return the object's scope lock count decreases by one.
"*" or " " (blank character): the asterisk indicates that the activity holds the object scope lock. Guarded methods are blocked, if they do not hold the object's scope lock. Methods in the unguarded state will never block.
"W" or " " (blank character): the capital W indicates that the method is waiting on the guard condition to turn .true.

Notes:

The GUARD keyword instruction can be used within a method to change the state from guarded (synchronize on the object scope lock) to unguarded (ignore the object scope lock) using unconditionally the keyword statement GUARD OFF and vice versa (using unconditionally the keyword statement GUARD ON). The GUARD keyword statement can only execute after successfully acquiring the object's scope lock.
The keyword instructions "GUARD ON WHEN someAttribute=someValue" and "GUARD OFF WHEN someAttribute=someValue" allow changing the state of the method to guarded or to unguarded depending on the value of an exposed attribute "someAttribute" which needs to get changed in another concurrently running method of the same scope. Such attributes are known to be used as "control variables" to synchronize activities on different threads. The GUARD keyword statement can only execute after successfully acquiring the object's scope lock.
The "attribute pool" ("object variable dictionary") number represents a specific object at a specific scope.
Methods in the guarded state that do not possess the trailing asterisk are blocked, they are waiting for the object scope lock.
Methods in the unguarded state are never blocked. If you wish to directly change the value of any exposed attribute in the same scope then make sure that the changes take place in the guarded state to inhibit concurrent updates from other threads to inhibit inconsistent states. Alternatively, the ooRexx semaphore classes (EventSemaphore Class, MutexSemaphore Class) could be used for that purpose.
The layout of the bracketed (multithreaded) prefix is intentionally designed to make parsing and analyzing the trace output of complex multithreaded ooRexx programs easy.

Starting with ooRexx 5.1, each traced line will be represented with an instance of its new class TraceObject. Its class attribute "option" is set to "N" (normal) by default. If one needs the additional, multithreaded related trace information prefixed in square brackets then changing the class attribute "option" to "S" (standard) or to "F" (full, for complex multithreaded programs) will prepend it to each traced line. Each such TraceObject instance will be sent as the argument to the LINEOUT message to the .traceOutput monitor object. As .traceOutput monitor needs a string value for display it will send the request("STRING") message to it, causing the TraceObject's makeString method to run and to return the string value that represents it.

If one wishes to intercept the generated TraceObject instances then one could take advantage of TraceObject's class attribute collector.