| 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. |