[v4,5/5] Adopt doc for TST_RETRY_FUNC for LTP_TIMEOUT_MUL

Mention that time limit is mulitplied with LTP_TIMEOUT_MUL.
---
 doc/test-writing-guidelines.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Hello,

Clemens Famulla-Conrad <cfamullaconrad@suse.de> writes:

> Mention that time limit is mulitplied with LTP_TIMEOUT_MUL.
> ---
>  doc/test-writing-guidelines.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt
> index efff4d40c..905a4baa5 100644
> --- a/doc/test-writing-guidelines.txt
> +++ b/doc/test-writing-guidelines.txt
> @@ -2313,7 +2313,8 @@ Retry a function in limited time
>  Sometimes LTP test needs retrying a function for many times to get success.
>  This achievement makes that possible via keeping it retrying if the return
>  value of the function is NOT as we expected. After exceeding a limited time,
> -test will break from the retries immediately.
> +test will break from the retries immediately. The time limit is multiplied
> +with LTP_TIMEOUT_MUL.

I think the function tst_multiply_timeout also needs documenting.

>  
>  [source,c]
>  -------------------------------------------------------------------------------
> -- 
> 2.16.4

Hi,

> Clemens Famulla-Conrad <cfamullaconrad@suse.de> writes:

> > Mention that time limit is mulitplied with LTP_TIMEOUT_MUL.
> > ---
> >  doc/test-writing-guidelines.txt | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)

> > diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt
> > index efff4d40c..905a4baa5 100644
> > --- a/doc/test-writing-guidelines.txt
> > +++ b/doc/test-writing-guidelines.txt
> > @@ -2313,7 +2313,8 @@ Retry a function in limited time
> >  Sometimes LTP test needs retrying a function for many times to get success.
> >  This achievement makes that possible via keeping it retrying if the return
> >  value of the function is NOT as we expected. After exceeding a limited time,
> > -test will break from the retries immediately.
> > +test will break from the retries immediately. The time limit is multiplied
> > +with LTP_TIMEOUT_MUL.

> I think the function tst_multiply_timeout also needs documenting.
Isn't it meant to be used just in library (in lib/tst_test.c)?
Thus I wouldn't document it here. And in fact remove it from include/tst_test.h
(second commit).

Kind regards,
Petr

On Mon, 2019-10-21 at 15:15 +0200, Petr Vorel wrote:
<snip>
> > I think the function tst_multiply_timeout also needs documenting.
> 
> Isn't it meant to be used just in library (in lib/tst_test.c)?
> Thus I wouldn't document it here. And in fact remove it from
> include/tst_test.h
> (second commit).

I'm ok with private function. But you need to make it available to
tst_common.h. We could use extern. But not sure if this is what we
want.

On the other hand, we could make it as lib function, so others, who
need to set timeout in arbitrary way, have a utility to adjust there
timeout in a generic way. WDYT? But we also could leave this for later,
and simply change it if really needed.

Thanks
Clemens

Hi Clemens,

> > Isn't it meant to be used just in library (in lib/tst_test.c)?
> > Thus I wouldn't document it here. And in fact remove it from
> > include/tst_test.h
> > (second commit).

> I'm ok with private function. But you need to make it available to
> tst_common.h. We could use extern. But not sure if this is what we
> want.

> On the other hand, we could make it as lib function, so others, who
> need to set timeout in arbitrary way, have a utility to adjust there
> timeout in a generic way. WDYT? But we also could leave this for later,
> and simply change it if really needed.
Well, it's not that important to complicate things.
My point was, that function is used only internally, unlike tst_set_timeout()
and tst_timeout_remaining() which are also used in some tests.

> Thanks
> Clemens

Kind regards,
Petr

Hi!
> I think the function tst_multiply_timeout also needs documenting.

That depends on if we want to export it or not.

We may as well keep it in API and create a helper under testcases/lib/
tehn we could use the C code that can multiply precisely in the shell as
well. But I do not care that much either way...

> Hi!
> > I think the function tst_multiply_timeout also needs documenting.

> That depends on if we want to export it or not.

> We may as well keep it in API and create a helper under testcases/lib/
> tehn we could use the C code that can multiply precisely in the shell as
> well. But I do not care that much either way...
+1. I wouldn't export it unless it's needed.

Kind regards,
Petr