Print a (rate-limited) warning when UMA zone is full.

[Bruce Evans]

On Fri, 30 Nov 2012, Pawel Jakub Dawidek wrote:

> On Fri, Nov 30, 2012 at 09:53:41AM +1100, Bruce Evans wrote:
>>>> When UMA zone is created, one can add configure a warning that should be
>>>> printed when UMA zone is full by calling:
>>>>
>>>> 	uma_zone_set_warning(socket_zone,
>>>> 	    "kern.ipc.maxsockets limit exceeded, please see tuning(7).");
>>
>> Please don't clone messages of this form.  It has bad grammar, bad
>> style and a garbage pointer.  Many of these were cloned from previous
>> messages of this form.
>>
>> Bad grammar:
>> 1. Redundant "limit".  kern.ipc.maxsockets is already a limit.
>
> I don't think I can agree here. kern.ipc.maxsockets is not only a limit
> - it is a string, a sysctl, a tunable... being specific that we are
> talking about kern.ipc.maxsockets limit is a good thing, IMHO.

There is nothing to disagree on -- this is a matter of fact.  If the
sysctl were named kern.ipc.limitsockets ("limit" instead of "max")
or just "limit", then the redundancy would be even clearer and uglier.

>> 2. Wrong object.  The thing not being exceeded is the number of sockets,
>>     not the limit on the number of sockets.
>> 3. Wrong verb.  It is impossible to exceed an enforcible, enforced limit
>>     This seems hard to fix without making the message too verbose.  A full
>>     description would say something to the effect that that the limit would
>>     be exeeded if exceeding it were possible and permitted.  Or some
>>     conventional wording for this situation could be used.  The above has
>>     conventional wording, but has too many errors for me.
>
> I agree 'exceeded' is wrong word here, I copied the message from
> kern.maxfiles warning, but really the messages in the patch were just
> examples how the new function can be used.
>
> How about this:
>
> 	The kern.ipc.maxsockets limit has be reached.
>
> The message is short. It tells what to tune. It gives sysctl name, so
> hopefully sysctl description will tell more about this limit. I'm not a
> native English speaker, so I'm open to other suggestions of course.

"has be reached" should be "has been reached", which sounds too formal
and verbose to me.  It has a complicated tense, so it may be especially
difficult for non-native English speakers.

Further fixes to the kern.ipc.maxpipekva message (change "exceeded" to
"reached" and remove the reference to tuning(7)) and copying them here
gives:

 	kern.ipc.maxsockets reached

If you want to use "limit" and have perfect grammar, then correct use
would be:

   The limit on the number of sockets (kern.ipc.maxsockets) [has been] reached.

This is too verbose for me.

>> 6. termination with a ".'.  Error messages are conventionally not terminated
>
> We probably won't reach an agreement here. In my opinion every sentence
> should be terminated with a period. Also it is a warning not an error
> message.

Again, there is nothing to disagree on.  It is a fact that error messages
and sysctl descriptions are conventionally not terminated with a "." in
BSD.  This at least saves space.  For error messages, it avoids some
technical problems.  The perror(), err() and warn() APIs append a colon,
a space, strerror(errno) (except for perror(NULL), and a newline.  Any
termination of the application's string by a "." would give the garbage
punctuation ".:" after the colon is appended.  These APIs never append
a "." after strerror(errno).  This is a major source of unterminated error
messages.

If you insist on the ".", then I will insist on perfect grammar (within
space constraints), including when something adds a prefix or a suffix :-).
Perfect grammar is difficult using the err() family, and terminating
with a "." is impossible for err() and warn().  You would have to subvert
the API and use errx() and warnx() with %s and strerror(errno) to get
enough control over the output to just terminate it with a ".".

Bruce