Re: parallel vacuum - few questions on docs, comments and code

On Thu, May 13, 2021 at 3:25 PM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
>
> On Wed, May 12, 2021 at 6:37 PM Bharath Rupireddy
> <bharath(dot)rupireddyforpostgres(at)gmail(dot)com> wrote:
> >
> > On Wed, May 12, 2021 at 11:10 AM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
> > >
> > > On Tue, May 11, 2021 at 5:38 PM Bharath Rupireddy
> > > <bharath(dot)rupireddyforpostgres(at)gmail(dot)com> wrote:
> > > >
> > > > I was going through the parallel vacuum docs and code. I found below
> > > > things, please someone clarify:
> > > >
> > > > 1) I see that a term "parallel degree" is used in the docs, code
> > > > comments, error messages "parallel vacuum degree must be a
> > > > non-negative integer", "parallel vacuum degree must be between 0 and
> > > > %d". Is there any specific reason to use the term "parallel degree"?
> > > > In the docs and code comments we generally use "parallel workers".
> > > >
> > >
> > > The parallel degree term is used here to indicate that we compute how
> > > much parallelism we can achieve based on the indexes.
> >
> > Yeah, I get it. Even if users don't specify a parallel option there
> > are chances that parallelism is picked. So the parallel degree is the
> > final number of workers that are chosen by the server for vacuuming
> > indexes. And, I think that parallel degree is something internal to
> > the server, and it's better we replace it in the vacuumdb.sgml, change
> > PARALLEL_DEGREE to PARALLEL_WORKERS in vacuumdb.c and change the error
> > message "parallel vacuum degree must be a non-negative integer" to
> > "parallel workers for vacuum must be greater than or equal to zero".
> >
> > Thoughts?

I'm fine with this change.

> >
> > > > 2) The error messages "parallel vacuum degree must be between 0 and
> > > > %d" and "parallel option requires a value between 0 and %d" look
> > > > inconsistent.
> > > >
> > >
> > > I think we can make them consistent.
> >
> > How about only one message "parallel option requires a value between 0
> > and %d" for both cases below? IMO they essentially mean the same
> > thing.

The change looks good to me in terms of consistency but even the
current messages also make sense and are slightly clearer to me aside
from using the term "degree". If the user lacks an integer after
PARALLEL option, we say "parallel option requires a value between 0
and %d" and if the user specifies an invalid number to the option we
say "parallel vacuum degree must be between 0 and %d”. We use the
message something like “AAA must be between X and Y” also in other
places if users input an invalid value. I'm not sure the consistency
is important here but another idea to improve the error message would
be to change "parallel vacuum degree must be between 0 and %d” to "the
number of parallel workers must be between 0 and %d” (or using
“parallel workers for vacuum” instead of “the number of parallel
workers”) while leaving another message as it is.

Regards,

--
Masahiko Sawada
EDB: https://www.enterprisedb.com/