6. DATA SOURCES › 6.3 Contention For "Logical" (ENQ) Resources

6.3 Contention For "Logical" (ENQ) Resources

Contention exists for a logical resource (ENQ) whenever a
task in memory requests use of it, and that request is forced
to wait because it may not have it.  For all logical
resources with a "scope" (see ENQSCOPE) of SYSTEM or SYSTEMS,
RMF is informed that this has happened because an ENQHOLD
SYSEVENT is issued to inform SRM of this occurence.  RMF has
an exit that gets control at this point if the user has
requested ENQ measurements.  Note that IEAVENQ1 (the ENQ/DEQ
routine) does not issue SYSEVENTs for ENQ contention for
resources with a scope of STEP.

SRM needs to be informed about ENQ contention because it
would like to take some action to expedite the execution of
the holders of the resource.  Memories that are IN/READY are
marked as not to be swapped out until they have received an
ERV's (Enqueue Residency Value) worth of service.  Memories
holding the resource that are OUT/READY are marked for
consideration for swap-in the next time IRARMCAP gets
control.  IRARMCAP will swap such memories in even if to do
so would take the target domain over its target or even max
MPL.  At the same time, IRARMCAP will attempt to swap out
IN/READY users to "make room" for the memory coming in
(memories swapped out to make room are said to be OUT/READY
because of an ENQ EXCHANGE swap) if necessary to maintain MPL
limits.  Also, if a memory holding a desired resource is
executing in the mean-time-to-wait group, it is given the
maximum MTW priority to expedite its processing.

To understand the RMF ENQ measurements, you must know when
and why ENQHOLD and ENQRLSE SYSEVENTS are issued, and how RMF
responds to these SYSEVENTS when it gets control.

IEAVENQ1 issues a ENQHOLD whenever a RESERVE ENQ is issued by
an authorized program and that program gets control of the
resource.  The purpose of this appears to be to expedite
memories holding inter-CPU resources without leaving a hole
in SRM control to be exploited by unscrupulous non-authorized
users.  RMF filters out ENQHOLDs issued for resources for
which there are no requests waiting, so this is not a
problem.  Similarly, RMF filters out the ENQRLSE that is
issued when the same authorized program releases the RESERVE
via the DEQ macro instruction.

IEAVENQ1 also issues ENQHOLDs whenever it queues the FIRST
waiting request for a resource.  ENQHOLD actually supplies
the ASID of the holders of the ENQ, not of the waiter,
because it is the holders that must be given extra execution
consideration.  An ENQHOLD is issued for EACH holder; there
may be more than one when the resource is held SHR and the
waiter requests OLD (exclusive).

IEAVENQ1 issues ENQRLSE whenever a DEQ is issued for a
resource for which there is a queue.  The ENQRLSE passes the
ASID of the releasing memory to SRM so that memory can be
taken out of special ERV status.  Note, however, that the
waiters for the ENQ do not necessarily get control at this
point; the ENQ may have been held SHR with multiple holders.
The first waiter (if OLD (exclusive) requested) or possibly
waiters (if SHR) requested on the queue will not be given the
resource until ALL holders have DEQ'ed (and, therefore,
ENQRLSEs have been issued for them).

Note that the above would not quite work if it were possible
for a SHR requestor to be given control of a resource
currently held SHR while an OLD (exclusive) requestor was
waiting in the queue for it. RMF would see more ENQRLSEs than
ENQHOLDs.  This does not happen because a SHR requestor for a
resource held SHR will wait behind an OLD (exclusive) waiter.
This is done to prevent the OLD (exclusive) requestor from
waiting indefinitely if there is a parade of SHR requestors.

If there is a queue of requestors for a resource, not all of
which will get control when the current holders release
control (for example, if there are a number of OLD exclusive
requests waiting), there will be no ENQHOLDs outstanding at
the time the queue is promoted.  When the first waiters are
given control, IEAVENQ1 notes that there is a waiter for the
resource and will issue ENQHOLDs for holders just given
control.

For each resource (unique major name/minor name/scope
combination) being tracked, ERBMFEEQ keeps a counter that is
incremented for an ENQHOLD and decremented for an ENQRLSE.
The purpose of this counter is to prevent multiple-counting
of statistics when multiple ENQHOLD/ENQRLSE sequences occur
because there was more than one holder (SHR) of the resource
when a request had to wait.

RMF counts a "contention event" when this counter goes from
zero to one, begins timing the contention event at this
point, and gathers information about the holders and waiters.
RMF does not, however, update most data elements that come
out in the record until the ENQRLSE is received, which causes
this internal counter to go to zero.  Note that what is being
counted here as a contention event is not the same thing that
is documented in the RMF manual.  The RMF manual implies that
a contention event begins when delay begins (the first
request is queued) and ends when the last request queued gets
control.  Actually, a new contention event is counted each
time the queue for the resource is promoted, even if there
are still waiters after this happens.

When the "last" ENQRLSE is received (the one that causes the
internal counter to go to zero), RMF decides that the
"contention event" has ended and determines its elapsed time.
It also sets a number of statistics about the event such as
the number of waiters in the queue (the queue has not been
promoted at this point so there must be at least one waiter).
This statistic find its way out as SMF77QLT.

There is an RMF concept called the "period of maximum
contention."  (In the description of the RMF Enqueue Activity
(type 77) record, variables whose values are taken at what
RMF determines to be the period of maximum contention are
called "current" values).

RMF (module ERBMFEEQ) maintains a control block for each
major/minor qname (ENQ) being monitoring.  In the control
block RMF maintains essentially two sets of fields for all
those variables defined as being at "maximum contention." An
example is SMF77DO1, which is defined in the RMF manual as
"Job Name 1 of current resource owner."

When an ENQHOLD occurs for a resource, RMF runs the QELs to
count the number of waiters for it.  If the count is greater
than his old "maximum waiters" counter, then its value
replaces the old maximum.  At the same time, RMF decides it
is at maximum contention for this resource WITHIN THIS
SPECIFIC CONTENTION EVENT, so it stores the jobname of the
first job on the queue that owns the contended-for resource
in a holding field.  When the last ENQRLSE (the one that
causes it to decrement the internal counter mentioned above
to zero) comes through, ERBMFEEQ notes how long the
"contention event" (first ENQHOLD to last ENQRLSE) existed.
If this time is greater than the previous longest time for
this resource during the current interval, then RMF will copy
the jobname it saved in the holding field to SMF77DO1.  If it
is not the longest contention event, then the old value of
SMF77DO1 is not replaced, even though the queue length for
the resource may have been much longer during this shorter
contention event than it was during the longest one so far,
from which the SMF77DO1 value was taken.

In summary, then, the period of "maximum contention" is the
moment at which the longest queue existed for the resource
during the longest contention event that existed during the
interval.  Note that this is at variance with the explanation
in the RMF manual, which implies that the period of maximum
contention is that point at which the longest queue existed.

The same logic is used for all the "maximum contention"
fields.