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
