| Timeouts in CHERIoT-RTOS |
| ======================== |
| |
| CHERIoT RTOS aims to provide a consistent notion of timeout for APIs. |
| |
| Ticks |
| ----- |
| |
| Timeouts are described in terms of 'ticks'. |
| A tick is the time between two scheduling events, bounded by a time specified in the [board description file](BoardDescriptions.md). |
| In the current scheduler design, the hardware timer fires once every tick and performs a context switch. |
| A future tickless design will likely adjust this slightly and redefine a tick an upper bound on a scheduler operation, such that a voluntary yield causes a tick to finish early. |
| |
| The macros in [`tick_macros.h`](../sdk/include/tick_macros.h) provide helpers for converting between ticks and milliseconds. |
| These are approximate and code that has strong timing requirements should query a timer after waking from a timeout. |
| |
| Timeouts |
| -------- |
| |
| Timeouts are described by the `Timeout` structure in [`timeout.h`](../sdk/include/timeout.h). |
| These describe the number of ticks that *have* elapsed and the number of ticks remaining that *may* elapse before a timeout occurs. |
| The special value `UnlimitedTimeout` indicates that an unbounded number of ticks may elapse. |
| |
| Each function that may block should take a pointer to a `Timeout` structure. |
| This API structure is intended to allow chaining. |
| The same `Timeout*` is passed to any scheduler API that can suspend the calling thread and will time out if the remaining number reaches zero. |
| The caller may then inspect the `elapsed` field to see how many ticks have elapsed while blocking. |
| |
| Note that the `elapsed` number of ticks at the end of a blocking operation may exceed the initial `remaining` value (i.e. the maximum timeout). |
| When a timeout expires, the thread becomes runnable but a higher-priority thread may still prevent it from running. |
