poll-scheduler-scan — why a Niagara bus misses the rate it was given

Install and run

# download it
curl -O https://plantroomlabs.com/tools/poll-scheduler-scan.py

# read the scheduler in the default install
python3 poll-scheduler-scan.py

# or name the installation to read
python3 poll-scheduler-scan.py /opt/Niagara/Niagara-4.15.5.22

The three rates, and what they are a budget for

The three rates, read out of the static initialiser, not the docs:
  fastRate      1000 ms   (min facet 1 ms, showMilliseconds)
  normalRate    5000 ms   (min facet 1 ms, showMilliseconds)
  slowRate     30000 ms   (min facet 1 ms, showMilliseconds)
  pollEnabled lives on BAbstractPollService, with actions
  enable and disable. While it is false the thread sleeps
  1000 ms a turn and polls nothing.

One point per pass, and nothing floors the gap

Step 2. pollQueue polls EXACTLY ONE pollable per pass - one
        ArrayList.get and one poll() call - walking the bucket
        round-robin on its own index cursor. A bucket is due when
        nextTicks <= now + 5 ms.

        It then re-schedules itself, and this is the whole of it:
          next = (rate - size * elapsed) / size   i.e. rate/size
                                                  minus elapsed
          nextTicks = now + next
        where size is the bucket's point count and elapsed is how
        long that single poll actually took. An empty bucket
        re-schedules at 1000 ms.

        There is no Math.max in the method. Nothing floors next.

Step 3. So when a poll takes longer than its share of the rate,
        next falls to zero and then below it, nextTicks lands at
        or before now, and the bucket is due again at once. The
        sleep itself is behind an ifle, so zero is already enough.
        computeSleep() starts at 1000 ms and takes the min over all
        three buckets' nextTicks
        minus now, so it returns that same number or less, and
        the sleep is skipped outright.

        The poll thread stops sleeping. It does not log, it does
        not set a status, and it does not slow the bus down. It
        just stops idling, and the real cycle time stretches to
        size * elapsed instead of the rate that was asked for.

        Derived from the constants above, not asserted - the
        largest fast bucket that still leaves a positive gap
        between polls, so the thread still sleeps at all:
            2 ms per poll ->   333 points, and 334 points gives next = 0 ms
            5 ms per poll ->   166 points, and 167 points gives next = 0 ms
           10 ms per poll ->    90 points, and 91 points gives next = 0 ms
           20 ms per poll ->    47 points, and 48 points gives next = 0 ms
           50 ms per poll ->    19 points, and 20 points gives next = 0 ms
        On an RS-485 multidrop a request and its reply is tens of
        milliseconds, so those are the point counts that matter.

The evidence a station gives you for this

Step 6. What evidence you get, which is 14 properties, all String:
          averagePoll       busyTime          totalPolls
          dibsPolls         fastPolls         normalPolls
          slowPolls         dibsCount         fastCount
          normalCount       slowCount         fastCycleTime
          normalCycleTime   slowCycleTime
        Every one is flags 3 - READONLY|TRANSIENT - and defaults
        to the string "-". statisticsStart defaults to
        BAbsTime.NULL, and resetStatistics is flags 128
        (CONFIRM_REQUIRED).

        Being Strings, they are already rounded and already
        formatted when you read them:
          cycle times  "average = N ms", integer division, and
                       "-" until the first cycle completes
          counts       plain below 10000, then (n/1000) + "k"
          durations    "Nms" below 10000 ms, then (n/1000) + "sec"
        and they are recomputed only every 10000 ms.

        TRANSIENT means they are not saved, so a station restart
        clears them. String means you cannot put a history
        extension on them, cannot link them to a numeric and
        cannot set an alarm on them. The one number that says your
        bus is saturated is a piece of text, read by eye.

What follows from it

Three consequences worth designing for
----------------------------------------------------------------------
  1. Overrun is silent and self-inflicted. The scheduler reacts
     to a slow bus by not sleeping, never by reporting. If your
     driver needs an operator to know the cycle has stretched,
     the driver has to say so itself.
  2. Rate is a budget per bucket, not per point. Doubling the
     points in a bucket halves each point's share, so adding
     points to a working network can push it over with no
     configuration change anywhere.
  3. The statistics cannot be trended. If cycle time matters to
     your customers, expose it as a numeric of your own.

Three checks one station settles in an afternoon
----------------------------------------------------------------------
  1. Put N points on one slow bus at the default 1000 ms fast rate
     and read fastCycleTime: it will say "average = ..." well
     above 1000 once N * elapsed exceeds it.
  2. Watch the poll thread's CPU while that is true - the sleep
     is being skipped every pass.
  3. Open a graphic with many points on it and watch the periodic
     poll stall while the dibs stack drains.

What it reads, and the limit of what the output is worth

The file you are downloading