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
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
