Undocumented boolean returned by PeriodicTimer.WaitForNextTick?

[fterrani]

Type of issue

Missing information

Description

Greetings.

I don't have much time to look more in details but it seems to me that the boolean value returned by WaitForNextTick is not clearly documented. Three possible events are mentioned:

• timer firing
• Dispose() call
• task cancellation

But the boolean value's meaning in relation to this isn't explicitly described. My guess would be that it is true if the timer fired and false in any other case?... But, well, that's a guess! :)

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.threading.periodictimer.waitfornexttickasync?view=net-8.0#system-threading-periodictimer-waitfornexttickasync(system-threading-cancellationtoken)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading/PeriodicTimer.xml

Document Version Independent Id

0ef31de4-0c6b-4ae5-b172-c2e89beee4cc

Article author

@dotnet-bot

[fterrani]

I think it would also be important to be more explicit about what happens if ticks "coalesce". I don't find it very clear... For example:

• Let's way have a 1-hour period.
• T0: We initialize the timer. First job will occur in 1 hour. (EDIT: of course, we call WaitForNextTick immediately after initializing and immediately each time after the periodic job is finished)
• T1: On hour passed, a tick occurs, the job is started.
• The job takes 2.5 hours which means T2 and T3 will coalesce into a single tick.
• T3.5: what happens now? will another tick occur immediately? or will PeriodicTimer wait for T4 to fire a new tick?

According to this, another tick occurs immediately at T3.5. If so, the documentation misleading:

Waits for the next tick of the timer, or for the timer to be stopped.

The reader will probably think the next tick is the next "scheduled" tick (that is, the set of ticks described by t0 + k * period with t0 being the moment the timer was created and k a strictly positive integer).

EDIT: Tick coalescing is, I think, a way of saying that ticks don't "accumulate" but it doesn't tell anything about what happens if we are "late" for a tick.

[fterrani]

Some content ideas for the method's description:

Waits for the next tick of the timer, or for the timer to be stopped. If at least one tick occurred since the timer's construction or since the last call to this method, it returns immediately.

... and for the Remarks section:

The PeriodicTimer behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between calls to WaitForNextTickAsync(CancellationToken). In other words, ticks are not queued in any way and only the latest one matters.

Also, don't you think this wording kind of suggest tick queuing? It might be better to limit the description to what will concretely happen with the Task, boolean and waiting time instead of using a terminology that both suggests tick multiplicity and introduces the idea of individual tick consumption?

Similarly, a call to Dispose() will void any tick not yet consumed.

[gfoidl]

For reference: the same question is in https://github.com/dotnet/dotnet-api-docs/issues/10274 (but this here some more questions, I'd close the other one instead)