CMLOG Throttling Requirements
-----------------------------

Document Modifications:

5/16/01 - Ron MacKenize - Added item 0, indicating that there could be a new call.
5/11/01 - Ron MacKenzie - Added the need for solaris (and other platform support)
4/27/01 - Lazmo, Steph, Kristi, and Ronm.  Original version after a meeting
          where current capability was presented and Kristi and Steph presented
          vxWorks needs.

---------------------

Mike (lazmo@slac) has done very good detective work in discovering what the current
implementation of setThrottle() does.  The end result of that
investigation tells us that the current implementation won't meet our
needs.  Here's what we need:

0. Note:
Below, we refer to modifications to the current setThrottle call which 
is part of the current cmlog API.  This is done mostly as a discussion tool
for stating the requirements as being improvements over the current functionality.
It may end up being possible to meet the requirements by providing a completely new 
call apart from cmlogSetThrottle.

1.
The current functionality meters on a Tag, not the contents of the Tag.
The setThrottle() call needs to have an additional input parameter which
is the "contents" of the tag to be metered.  Metering will occur on that
contents value, not on the tag itself as the current implementation does.
"Contents" may be of any appropriate data type including string.

2.
It should be possible to meter(throttle) on several different values at
once for a given tag.  That is, a user can call setThrottle() several
times with the same tag and different contents values.  The user shall
also be able to call several times with different tag values.

3.
For string metering, it should be possible to specify a substring in the
"contents" input parameter.  For example, the user may
specify to meter on strings that contain the tag value "cat" (in the text
tag).  Metering would occur if the actual string is "catdog".

4.
There should be a way to turn off metering for a given tag/value.  It is
also desirable to be able to turn off metering for all values
for a tag and also turn off metering completely.  This may be possible by
just passing zero in some parameter of the setThrottle call.

5.
Summary messages should be provided both when metering begins and when it
ends.  The summary message issued when metering begins should indicate the
tag/message that is being metered.  The summary message that is issued
when when normal message flow resumes for a given tag/value should specify
how many messages got dropped and what the tag/value was.

6.
The "c" and "c++" api calls should both be provided so that the general
cmlog community can plug the new calls into applications written in either
language.

7.
This is probably obvious, but it needs to be possible to make the setThrottle
call from the shell or a program (on vxWorks).

8.
Epics error messages are normally longer than that 40 characters.  
There is a 40 characters limit for the substring that we'll pass to
setThrottle which is plenty generous enough.  Note that we do NOT
need any wild-carding as we first discussed (Mike had said something
about that in his mail to Jie). [Steph]

9.
It needs to be verified that all types of messages originating in the ioc
will be metered (eg. logMsg, epicsPrintf, etc), no matter the source.  For
example, even messages caused by network disruptions are to be metered.
Likewise messages from strange loops that might occur at boot time are
also to be metered.

10.
The new throttling capability needs to implemented for all platforms
which are supported by cmlog make files.  That's so we can get it 
incorporated into the general cmlog release by Jie.  For specific needs at 
slac at this point, we need to test this new capability on vxWorks and solaris.
Under solaris, it needs to work with CC and gcc makes.

Additional Notes:
Ultimately, this new setThrottle() metering call will be plugged into epics
records.  That way, a user shall be able to use a dm display to input
tag values (the tag will always be "text") for each setThrottle call that is made.
We may also be able to provide the other args in setThrottle 
without too much trouble.
That type of display shall be capable of turning on and off metering on
each of those values.  It shall also be capable of displaying all current
items being metered. [input for this from Steph too]

Across ioc reboots, the save and restore of metering will occur via the
epics record which contains the current metering call.

Stephanie wondered if cmlogVxLogMsg replaces logMsg in the vxWorks
architecture.   I guess we need to understand the architecture (and how
cmlog plugs into vxWorks and epics) a little more.