[En-Nut-Discussion] NutGetMillis overflow documentation

[Jose Vallet]

Hello Ulrich, and thanks for your answer.

Ulrich Prinz escribió:
> Hi José,
> 
> anyone should be able to add a bugreport in sourceforge.
> But it may be, that you need to create an account there and assign to 
> the project.

Yes, you need to create an account in SourceForge, and I didn't want. I 
also tried with my google account through the OpenID, but I was having 
problems with it at that specific time, so I couldn't. Hope it works 
next time :)

> 
> However, you're right with your calculation. The question is, what do 
> you like to do with NutGetMillis()?

In our case, long time ago we decided to use the value returned from 
NutGetMillis as a time stamp for measurements within time limited 
experiments and to measure the time it takes to execute some procedures. 
These values are used for other computations of some controls, so it was 
important to not to have problems with overflows. The 7 years of the 
milliseconds counter overflow shown in the documentation was way more 
than enough for our purposes.

> Normally you do timespan calculations that look like this:
> 
> if( now-past < span) { wait a bit }
> 
> These type of call will result in a jitter with every overflow.
> 
> A second unusual usecase might be to determine the action to do now from 
> the exact time:
> 
> now = NutGetMilis();
> if (now == time1) { action1() }
> else if (now == time2) { action }
> 
> The example is simplified as you need to add some derivation to the 
> times. It will be very unlikely to hit a ms precisely. However both 
> examples are not a good way to use system timers in no system.
> 
> If you need an exact point of time to execute a function call, create 
> your own timer. Nut/OS allows to do this as well in the higher timer 
> functions as it allows it in the system timer too. For example one, you 
> can decide, if the function should sleep and give CPU to other pending 
> tasks (NutSleep(n)) or if it must stay in the actual thread and delay ( 
> NutDelay(n)).
> 
> For the second example it is a matter of how precise your calls need to 
> be. Add a call to the seconds counter update or add some small code to 
> the system timer. Your decision. Create your own counter, counting 
> exactly and only as high as needed, reset it in a controlled way or use 
> a state machine.
> 
> If a small ammount of jitter is acceptable, write a state machine thread 
> and use NutSleep or NutDelay as needed.
> 
> It is never, never, never a good idea to use a running counter with a 
> possible overflow for timing related calls. If this sounds a bit like a 
> teacher and if you know all that, forgive me, but the next guy stumbling 
> across that, this might help.

I totally agree with you in all these matters, but in our case time 
requirements are not very strict, a small jitter is acceptable and the 
experiments that we are running take normally a few hours, although the 
theoretical maximum spam is within the range of days (not being clear 
how many). So 7 years for the counter overflow sounded as a good enough 
guarantee for our purposes, and we designed all the control system being 
"in peace" about overflow issues.

However, it was a surprise when I first realized that the 7 years of the 
overflow turned out to be only 49 days, a huge difference being now much 
closer to the maximum possible time spam of our experiments. It was an 
issue to be concerned of, and we might have had to redesign some parts 
because of that. Fortunately in practice the experiments have been 
lasting always less than couple of hours, so we didn't have to change 
anything.

My point here was simple: the documentation is misleading in a point 
that might be important in some designs. And not only the documentation 
is wrong in the comments of the function, but also it is being written 
wrong in the rather new software manual, that is supposed to be up to 
date and something that a user will read with trust.

And BTW, even if I am not a complete beginner I appreciate your 
comments, it is always nice to get detailed explanations and most likely 
one turns out to learn something new (I did). Nothing to forgive :)

> 
> For now I add a tracker report for the wrong documentation.

Thanks.

José