Re: [PATCH v4 3/6] block-copy: improve comments of BlockCopyTask and BlockCopyState types and functions

[Emanuele Giuseppe Esposito]

On 19/06/2021 19:27, Vladimir Sementsov-Ogievskiy wrote:
> 14.06.2021 10:33, Emanuele Giuseppe Esposito wrote:
> > As done in BlockCopyCallState, categorize BlockCopyTask
> > and BlockCopyState in IN, State and OUT fields.
> > This is just to understand which field has to be protected with a lock.
> >
> > .sleep_state is handled in the series "coroutine: new sleep/wake API"
> > and thus here left as TODO.
> >
> > Signed-off-by: Emanuele Giuseppe Esposito<eesposit@redhat.com>
> > ---
> >   block/block-copy.c | 49 +++++++++++++++++++++++++++++-----------------
> >   1 file changed, 31 insertions(+), 18 deletions(-)
> >
> > diff --git a/block/block-copy.c b/block/block-copy.c
> > index 3f26be8ddc..5ff7764e87 100644
> > --- a/block/block-copy.c
> > +++ b/block/block-copy.c
> > @@ -52,29 +52,35 @@ typedef struct BlockCopyCallState {
> >       /* Coroutine where async block-copy is running */
> >       Coroutine *co;
> > -    /* To reference all call states from BlockCopyState */
> > -    QLIST_ENTRY(BlockCopyCallState) list;
> > -
> >       /* State */
> > -    int ret;
> >       bool finished;
> > -    QemuCoSleep sleep;
> > -    bool cancelled;
> > +    QemuCoSleep sleep; /* TODO: protect API with a lock */
> > +
> > +    /* To reference all call states from BlockCopyState */
> > +    QLIST_ENTRY(BlockCopyCallState) list;
> >       /* OUT parameters */
> > +    bool cancelled;
>
> actually, cancelled is not OUT field. It's set by user to cancel the 
> operation. And block-copy tracks the field to understand should it 
> cancel at the moment or not. So, it's part of state.

Makes sense.

> Also, I just now understand, that "out parameter" sounds strange here. 
> As "parameter" is an input by general meaning.. We may have "out 
> parameters" for functions, as all parameters of a function are generally 
> called "parameters" anyway. I think "OUT fields" is more correct here. I 
> don't insist, as I'm not an expert in English (for sure, you'll find 
> mistakes even in this paragraph :\
Actually I am using the terminology that was already there :)
Anyways, I am not expert here either but fields do sounds better.
I will change parameter -> field replacement to this patch.

Emanuele