diff options
author | Richard Braun <rbraun@sceen.net> | 2019-07-12 00:34:51 +0200 |
---|---|---|
committer | Richard Braun <rbraun@sceen.net> | 2019-08-16 03:57:13 +0200 |
commit | 204eec9be03f53b93d0f732c967a623f8e0843ef (patch) | |
tree | 491092a44d3a6193ad9cd21ca34a3ba10fdd79f2 | |
parent | a62edad69f70d1c86dfa51cc8a2e298bb966180b (diff) |
Document the timer API
-rw-r--r-- | kern/timer.c | 2 | ||||
-rw-r--r-- | kern/timer.h | 23 | ||||
-rw-r--r-- | kern/timer_i.h | 2 |
3 files changed, 17 insertions, 10 deletions
diff --git a/kern/timer.c b/kern/timer.c index 9495c0f2..979ee5ea 100644 --- a/kern/timer.c +++ b/kern/timer.c @@ -435,7 +435,7 @@ INIT_OP_DEFINE(timer_setup, INIT_OP_DEP(spinlock_setup, true)); void -timer_init(struct timer *timer, timer_fn_t fn, int flags) +timer_init(struct timer *timer, timer_handler_fn_t fn, int flags) { timer->fn = fn; timer->cpu = TIMER_INVALID_CPU; diff --git a/kern/timer.h b/kern/timer.h index 02b5bef7..9ebfd0e7 100644 --- a/kern/timer.h +++ b/kern/timer.h @@ -35,9 +35,11 @@ struct timer; /* - * Type for timer functions. + * Type for timer callbacks. + * + * These functions implement handler operations. */ -typedef void (*timer_fn_t)(struct timer *); +typedef void (*timer_handler_fn_t)(struct timer *); #include <kern/timer_i.h> @@ -59,7 +61,7 @@ timer_get_time(const struct timer *timer) * Timers that are reponsible for releasing their own resources must * be detached. */ -void timer_init(struct timer *timer, timer_fn_t fn, int flags); +void timer_init(struct timer *timer, timer_handler_fn_t fn, int flags); /* * Schedule a timer. @@ -67,11 +69,13 @@ void timer_init(struct timer *timer, timer_fn_t fn, int flags); * The time of expiration is an absolute time in ticks. * * Timers may safely be rescheduled after completion. Periodic timers are - * implemented by rescheduling from the handler. + * implemented by rescheduling from the timer handler. * * If the timer has been canceled, this function does nothing. A * canceled timer must be reinitialized before being scheduled again. * + * This operation synchronizes with handler operations on the same timer. + * * This function may safely be called in interrupt context. */ void timer_schedule(struct timer *timer, uint64_t ticks); @@ -81,13 +85,16 @@ void timer_schedule(struct timer *timer, uint64_t ticks); * * The given timer must not be detached. * - * If the timer has already expired, this function waits until the timer - * function completes, or returns immediately if the function has already - * completed. + * If the timer is still scheduled, it is canceled, i.e. its handler + * operation won't start. Otherwise, if the timer has already expired, + * this function waits until the handler operation completes, or returns + * immediately if the handler operation has already completed. * * This function may safely be called from the timer handler, but not on - * the current timer. Canceling a timer from the handler is achieved by + * the same timer. Canceling a timer from the timer handler is achieved by * simply not rescheduling it. + * + * Handler operations on the same timer synchronize with this operation. */ void timer_cancel(struct timer *timer); diff --git a/kern/timer_i.h b/kern/timer_i.h index 799b5ac9..6f5b69ed 100644 --- a/kern/timer_i.h +++ b/kern/timer_i.h @@ -40,7 +40,7 @@ struct timer { }; uint64_t ticks; /* (c) */ - timer_fn_t fn; + timer_handler_fn_t fn; unsigned int cpu; /* (c,a,*) */ unsigned short state; /* (c) */ unsigned short flags; /* (c) */ |