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 within an MVS 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 which gets control at this point if the user
has requested ENQ measurements.  Note that IEAVENQ1 (the MVS
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 holder(s) of the resource.  Memories which are IN/READY
are marked as not to be swapped out until they have received
an ERV's (Enqueue Residency Value - see PGAERF) worth of
service.  Memories holding the resource which 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, but 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, it is necessary to
know when and why ENQHOLD and ENQRLSE SYSEVENTS are issued,
and how RMF responds to these SYSEVENTS when it gets control.
IBM documentation on this subject is rather limited and the
following represents our understanding of the subject.

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 which is
issued when the same authorized program releases the RESERVE
via the DEQ macro instruction.

IEAVENQ1 also issues ENQHOLD(s) whenever it queues the FIRST
waiting request for a resource.  ENQHOLD actually supplies
the ASID of the holder(s) of the ENQ, not of the waiter,
because it is the holder(s) which 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
waiter(s) 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,
ENQRLSE's have been issued for them).

A very sharp-eyed reader might 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).

In the case when there is a queue of requestors for a
resource, not all of which will get control when the current
holder(s) releases control (say 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 waiter(s) is(are) given control, IEAVENQ1 notes that
there is a waiter for the resource and will issue ENQHOLDs
for holder(s) just given control.

For each resource (unique major name/minor name/scope
combination) being tracked, ERBMFEEQ keeps a counter which 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 and also begins timing the contention event at
this point and gathers information about the holders and
waiters.  RMF does not, however, update most data elements
which 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 which 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" which could stand some explanation.  (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, unhelpfully, termed
"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".
Take SMF77DO1 ( defined in the RMF manual as "Job Name 1 of
current resource owner") as an example.

When an ENQHOLD occurs for a resource, RMF runs the QEL's 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 which 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 which 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,
period.

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