Added to "15.4. Debugging Multithreaded Programs" under a new section "15.4.1. About Debugging
Guarded and Unguarded Methods". It fits better there and enables the reader to better understand the
remainder of that section.
Committed with [r12858], cf. <https://sourceforge.net/p/oorexx/code-0/12858/>.
---rony
On 13.07.2024 12:54, Rony G. Flatscher wrote:
Planning on adding the documentation at the end of section "12.4.3. Guarded
Methods" in rexxref.pdf.
---
Planning on the following improvements for TraceObject:
* add an entry ISWAITING for "GUARD ON|OFF WHEN condition" statements,
reflecting the state of
the evaluated condition; if condition is false, then ISWAITING will be set
to .true as the
method has to wait for the re-evaluation of the condition, it is set to
.false else (the
method continues to run),
* add an entry CALLERSTACKFRAME for each invocation entry: this should allow
to find out the
caller for that particular invocation when analyzing trace logs,
* change the format of "Standard" to include the attribute pool ID, add next
to the guarded
(G)/unguarded(U) indicator in lowercase "u" if a guarded method is
currently executing
unguarded and "g" if an unguarded method is currently executing guarded a
blank otherwise, a
"W" as the last column if waiting on a guard condition to succeed a blank
otherwise. To not
increase the space for the extended trace prefix the widths for the ID
values will be reduced
from the minimum of currently three to two digits which should cater for
tracing small to
medium sized ooRexx programs,
* change the format of "Full" to include next to the guarded (G)/unguarded(U)
indicator in
lowercase "u" if a guarded method is currently executing unguarded and "g"
if an unguarded
method is currently executing guarded a blank otherwise, a "W" as the last
column if waiting
on a guard condition to succeed a blank otherwise.
---rony
On 12.07.2024 16:28, Rony G. Flatscher wrote:
Here an attempt to improve the text for the rules:
*Rules for running guarded methods*
ooRexx ensures that guarded methods of the same scope (defined for the
same class) cannot
execute concurrently to protect access to its attribute pool (object
variable pool). To
do so, a counter-based guard lock is maintained for each scope, which
gets increased by
one if a guarded method gets invoked and decreased by one upon return.
If a guarded
method for the same scope gets invoked from another thread and the
scope's guard lock
counter is not zero, it gets blocked because another guarded method
holding the guard
lock is currently running in the same scope. Once the scope's guard
lock counter drops to
0 (no other guarded method runs currently), the blocked guarded method
can acquire the
guard lock, thereby increasing the guard lock counter to one and
starting to run.
1. Invoking a guarded method from the same thread, then it will
increase the guard lock
counter by one and, upon return, will decrease it by one. Invoking
an unguarded
method from the same thread will not change the guard lock counter.
2. Invoking a guarded method from another thread for a scope in which
a guarded method
is currently running will block the invocation until the scope's
guard lock counter
drops to 0 (no other guarded method for the same scope is running
anymore) and the
guard lock becomes free. In this situation, the blocked guarded
method will succeed
in acquiring the guard lock, increasing the guard lock counter to
one, and starting
running.
3. If a REPLY keyword statement is processed in a currently guarded
method, the
remaining instructions of the guarded method will remain guarded.
4. A GUARD ON keyword statement has no effect.
5. A GUARD OFF keyword statement changes the guarded method to an
unguarded method from
that point on, in the process reducing the guard lock counter by
one and removing the
guard lock.
*Rules for running unguarded methods*
1. Unguarded methods can always run concurrently with any other method
of the same scope.
2. If a REPLY keyword statement is processed in a currently unguarded
method, the
remainder of the invocation will continue on a different thread,
also unguarded.
3. A GUARD ON keyword statement changes the unguarded method to a
guarded method from
that point on, in the process increasing the guard lock counter by
one and acquiring
the guard lock.
4. A GUARD OFF keyword statement has no effect.
-----------------------------------------------------------------------------------------
Some notes and maybe some planned improvements to TraceObject:
* the extended trace log includes the attribute pool (object variable pool)
ID which allows for
distinguishing different instances for which the methods run; it is planned
to change the
"Standard" format of TraceObject to include the attribute pool ID,
* the extended trace log includes a hint in the case that a method is not
executing in the
defined state due to the use of GUARD OFF|ON. In the trace log above a
guarded method that
runs unguarded is marked with a small 'u' right next to the method's
defined state 'G'; it is
planned to add this information at runtime, if possible (and not to a trace
log as is the
case here),
* the extended trace log includes a hint 'W' (for waiting) for trace output
where a wait for
the guard lock takes place; ; it is planned to add this information at
runtime, if possible
(and not to a trace log as is the case here).
Any comments, suggestions?
---rony
_______________________________________________
Oorexx-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
