2 * Copyright (c) 2016 Cisco and/or its affiliates.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
17 * @brief TW timer implementation TEMPLATE ONLY, do not compile directly
22 TW (make_internal_timer_handle) (u32 pool_index, u32 timer_id)
26 ASSERT (timer_id < TW_TIMERS_PER_OBJECT);
27 #if LOG2_TW_TIMERS_PER_OBJECT > 0
28 ASSERT (pool_index < (1 << (32 - LOG2_TW_TIMERS_PER_OBJECT)));
30 handle = (timer_id << (32 - LOG2_TW_TIMERS_PER_OBJECT)) | (pool_index);
38 timer_addhead (TWT (tw_timer) * pool, u32 head_index, u32 new_index)
40 TWT (tw_timer) * head = pool_elt_at_index (pool, head_index);
41 TWT (tw_timer) * old_first;
45 new = pool_elt_at_index (pool, new_index);
47 if (PREDICT_FALSE (head->next == head_index))
49 head->next = head->prev = new_index;
50 new->next = new->prev = head_index;
54 old_first_index = head->next;
55 old_first = pool_elt_at_index (pool, old_first_index);
57 new->next = old_first_index;
58 new->prev = old_first->prev;
59 old_first->prev = new_index;
60 head->next = new_index;
64 timer_remove (TWT (tw_timer) * pool, u32 index)
66 TWT (tw_timer) * elt = pool_elt_at_index (pool, index);
67 TWT (tw_timer) * next_elt, *prev_elt;
69 ASSERT (elt->user_handle != ~0);
71 next_elt = pool_elt_at_index (pool, elt->next);
72 prev_elt = pool_elt_at_index (pool, elt->prev);
74 next_elt->prev = elt->prev;
75 prev_elt->next = elt->next;
77 elt->prev = elt->next = ~0;
81 * @brief Start a Tw Timer
82 * @param tw_timer_wheel_t * tw timer wheel object pointer
83 * @param u32 pool_index user pool index, presumably for a tw session
84 * @param u32 timer_id app-specific timer ID. 4 bits.
85 * @param u64 interval timer interval in ticks
86 * @returns handle needed to cancel the timer
89 TW (tw_timer_start) (TWT (tw_timer_wheel) * tw, u32 pool_index, u32 timer_id,
92 #if TW_TIMER_WHEELS > 1
96 #if TW_TIMER_WHEELS > 2
97 u16 glacier_ring_offset;
99 #if TW_OVERFLOW_VECTOR > 0
100 u64 interval_plus_time_to_wrap, triple_wrap_mask;
102 u16 fast_ring_offset;
103 tw_timer_wheel_slot_t *ts;
108 pool_get (tw->timers, t);
109 memset (t, 0xff, sizeof (*t));
111 t->user_handle = TW (make_internal_timer_handle) (pool_index, timer_id);
113 /* Factor interval into 1..3 wheel offsets */
114 #if TW_TIMER_WHEELS > 2
115 #if TW_OVERFLOW_VECTOR > 0
117 * This is tricky. Put a timer onto the overflow
118 * vector if the interval PLUS the time
119 * until the next triple-wrap exceeds one full revolution
120 * of all three wheels.
122 triple_wrap_mask = (1 << (3 * TW_RING_SHIFT)) - 1;
123 interval_plus_time_to_wrap =
124 interval + (tw->current_tick & triple_wrap_mask);
125 if ((interval_plus_time_to_wrap >= 1 << (3 * TW_RING_SHIFT)))
127 t->expiration_time = tw->current_tick + interval;
129 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
130 return t - tw->timers;
134 glacier_ring_offset = interval >> (2 * TW_RING_SHIFT);
135 ASSERT ((u64) glacier_ring_offset < TW_SLOTS_PER_RING);
136 interval -= (((u64) glacier_ring_offset) << (2 * TW_RING_SHIFT));
138 #if TW_TIMER_WHEELS > 1
139 slow_ring_offset = interval >> TW_RING_SHIFT;
140 ASSERT ((u64) slow_ring_offset < TW_SLOTS_PER_RING);
141 interval -= (((u64) slow_ring_offset) << TW_RING_SHIFT);
143 fast_ring_offset = interval & TW_RING_MASK;
146 * Account for the current wheel positions(s)
147 * This is made slightly complicated by the fact that the current
148 * index vector will contain (TW_SLOTS_PER_RING, ...) when
149 * the actual position is (0, ...)
152 fast_ring_offset += tw->current_index[TW_TIMER_RING_FAST] & TW_RING_MASK;
154 #if TW_TIMER_WHEELS > 1
155 carry = fast_ring_offset >= TW_SLOTS_PER_RING ? 1 : 0;
156 fast_ring_offset %= TW_SLOTS_PER_RING;
157 slow_ring_offset += (tw->current_index[TW_TIMER_RING_SLOW] & TW_RING_MASK)
159 carry = slow_ring_offset >= TW_SLOTS_PER_RING ? 1 : 0;
160 slow_ring_offset %= TW_SLOTS_PER_RING;
163 #if TW_TIMER_WHEELS > 2
164 glacier_ring_offset +=
165 (tw->current_index[TW_TIMER_RING_GLACIER] & TW_RING_MASK) + carry;
166 glacier_ring_offset %= TW_SLOTS_PER_RING;
169 #if TW_TIMER_WHEELS > 2
170 if (glacier_ring_offset !=
171 (tw->current_index[TW_TIMER_RING_GLACIER] & TW_RING_MASK))
173 /* We'll need slow and fast ring offsets later */
174 t->slow_ring_offset = slow_ring_offset;
175 t->fast_ring_offset = fast_ring_offset;
177 ts = &tw->w[TW_TIMER_RING_GLACIER][glacier_ring_offset];
179 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
181 return t - tw->timers;
185 #if TW_TIMER_WHEELS > 1
186 /* Timer expires more than 51.2 seconds from now? */
187 if (slow_ring_offset !=
188 (tw->current_index[TW_TIMER_RING_SLOW] & TW_RING_MASK))
190 /* We'll need the fast ring offset later... */
191 t->fast_ring_offset = fast_ring_offset;
193 ts = &tw->w[TW_TIMER_RING_SLOW][slow_ring_offset];
195 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
197 return t - tw->timers;
200 fast_ring_offset %= TW_SLOTS_PER_RING;
203 /* Timer expires less than one fast-ring revolution from now */
204 ts = &tw->w[TW_TIMER_RING_FAST][fast_ring_offset];
206 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
208 #if TW_FAST_WHEEL_BITMAP
209 tw->fast_slot_bitmap = clib_bitmap_set (tw->fast_slot_bitmap,
210 fast_ring_offset, 1);
212 return t - tw->timers;
215 #if TW_TIMER_SCAN_FOR_HANDLE > 0
216 int TW (scan_for_handle) (TWT (tw_timer_wheel) * tw, u32 handle)
219 tw_timer_wheel_slot_t *ts;
220 TWT (tw_timer) * t, *head;
224 for (i = 0; i < TW_TIMER_WHEELS; i++)
226 for (j = 0; j < TW_SLOTS_PER_RING; j++)
229 head = pool_elt_at_index (tw->timers, ts->head_index);
230 next_index = head->next;
232 while (next_index != ts->head_index)
234 t = pool_elt_at_index (tw->timers, next_index);
235 if (next_index == handle)
237 clib_warning ("handle %d found in ring %d slot %d",
239 clib_warning ("user handle 0x%x", t->user_handle);
242 next_index = t->next;
248 #endif /* TW_TIMER_SCAN_FOR_HANDLE */
251 * @brief Stop a tw timer
252 * @param tw_timer_wheel_t * tw timer wheel object pointer
253 * @param u32 handle timer cancellation returned by tw_timer_start
255 void TW (tw_timer_stop) (TWT (tw_timer_wheel) * tw, u32 handle)
259 #if TW_TIMER_ALLOW_DUPLICATE_STOP
261 * A vlib process may have its timer expire, and receive
262 * an event before the expiration is processed.
263 * That results in a duplicate tw_timer_stop.
265 if (pool_is_free_index (tw->timers, handle))
269 t = pool_elt_at_index (tw->timers, handle);
271 /* in case of idiotic handle (e.g. passing a listhead index) */
272 ASSERT (t->user_handle != ~0);
274 timer_remove (tw->timers, handle);
276 pool_put_index (tw->timers, handle);
280 * @brief Initialize a tw timer wheel template instance
281 * @param tw_timer_wheel_t * tw timer wheel object pointer
282 * @param void * expired_timer_callback. Passed a u32 * vector of
283 * expired timer handles. The callback is optional.
284 * @param f64 timer_interval_in_seconds
287 TW (tw_timer_wheel_init) (TWT (tw_timer_wheel) * tw,
288 void *expired_timer_callback,
289 f64 timer_interval_in_seconds, u32 max_expirations)
292 tw_timer_wheel_slot_t *ts;
294 memset (tw, 0, sizeof (*tw));
295 tw->expired_timer_callback = expired_timer_callback;
296 tw->max_expirations = max_expirations;
297 if (timer_interval_in_seconds == 0.0)
299 clib_warning ("timer interval is zero");
302 tw->timer_interval = timer_interval_in_seconds;
303 tw->ticks_per_second = 1.0 / timer_interval_in_seconds;
304 tw->first_expires_tick = ~0ULL;
305 vec_validate (tw->expired_timer_handles, 0);
306 _vec_len (tw->expired_timer_handles) = 0;
308 for (ring = 0; ring < TW_TIMER_WHEELS; ring++)
310 for (slot = 0; slot < TW_SLOTS_PER_RING; slot++)
312 ts = &tw->w[ring][slot];
313 pool_get (tw->timers, t);
314 memset (t, 0xff, sizeof (*t));
315 t->next = t->prev = t - tw->timers;
316 ts->head_index = t - tw->timers;
320 #if TW_OVERFLOW_VECTOR > 0
322 pool_get (tw->timers, t);
323 memset (t, 0xff, sizeof (*t));
324 t->next = t->prev = t - tw->timers;
325 ts->head_index = t - tw->timers;
330 * @brief Free a tw timer wheel template instance
331 * @param tw_timer_wheel_t * tw timer wheel object pointer
333 void TW (tw_timer_wheel_free) (TWT (tw_timer_wheel) * tw)
336 tw_timer_wheel_slot_t *ts;
337 TWT (tw_timer) * head, *t;
340 for (i = 0; i < TW_TIMER_WHEELS; i++)
342 for (j = 0; j < TW_SLOTS_PER_RING; j++)
345 head = pool_elt_at_index (tw->timers, ts->head_index);
346 next_index = head->next;
348 while (next_index != ts->head_index)
350 t = pool_elt_at_index (tw->timers, next_index);
351 next_index = t->next;
352 pool_put (tw->timers, t);
354 pool_put (tw->timers, head);
358 #if TW_OVERFLOW_VECVOR > 0
360 head = pool_elt_at_index (tw->timers, ts->head_index);
361 next_index = head->next;
363 while (next_index != ts->head_index)
365 t = pool_elt_at_index (tw->timers, next_index);
366 next_index = t->next;
367 pool_put (tw->timers, t);
369 pool_put (tw->timers, head);
372 memset (tw, 0, sizeof (*tw));
376 * @brief Advance a tw timer wheel. Calls the expired timer callback
377 * as needed. This routine should be called once every timer_interval seconds
378 * @param tw_timer_wheel_t * tw timer wheel template instance pointer
379 * @param f64 now the current time, e.g. from vlib_time_now(vm)
380 * @returns u32 * vector of expired user handles
383 u32 * TW (tw_timer_expire_timers_internal) (TWT (tw_timer_wheel) * tw,
385 u32 * callback_vector_arg)
388 tw_timer_wheel_slot_t *ts;
389 TWT (tw_timer) * t, *head;
390 u32 *callback_vector;
391 u32 fast_wheel_index;
393 u32 slow_wheel_index __attribute__ ((unused));
394 u32 glacier_wheel_index __attribute__ ((unused));
396 /* Shouldn't happen */
397 if (PREDICT_FALSE (now < tw->next_run_time))
398 return callback_vector_arg;
400 /* Number of ticks which have occurred */
401 nticks = tw->ticks_per_second * (now - tw->last_run_time);
403 return callback_vector_arg;
405 /* Remember when we ran, compute next runtime */
406 tw->next_run_time = (now + tw->timer_interval);
408 if (callback_vector_arg == 0)
410 _vec_len (tw->expired_timer_handles) = 0;
411 callback_vector = tw->expired_timer_handles;
414 callback_vector = callback_vector_arg;
416 for (i = 0; i < nticks; i++)
418 fast_wheel_index = tw->current_index[TW_TIMER_RING_FAST];
419 if (TW_TIMER_WHEELS > 1)
420 slow_wheel_index = tw->current_index[TW_TIMER_RING_SLOW];
421 if (TW_TIMER_WHEELS > 2)
422 glacier_wheel_index = tw->current_index[TW_TIMER_RING_GLACIER];
424 #if TW_OVERFLOW_VECTOR > 0
425 /* Triple odometer-click? Process the overflow vector... */
426 if (PREDICT_FALSE (fast_wheel_index == TW_SLOTS_PER_RING
427 && slow_wheel_index == TW_SLOTS_PER_RING
428 && glacier_wheel_index == TW_SLOTS_PER_RING))
431 u32 new_glacier_ring_offset, new_slow_ring_offset;
432 u32 new_fast_ring_offset;
435 head = pool_elt_at_index (tw->timers, ts->head_index);
436 next_index = head->next;
438 /* Make slot empty */
439 head->next = head->prev = ts->head_index;
441 /* traverse slot, place timers wherever they go */
442 while (next_index != head - tw->timers)
444 t = pool_elt_at_index (tw->timers, next_index);
445 next_index = t->next;
447 /* Remove from the overflow vector (hammer) */
448 t->next = t->prev = ~0;
450 ASSERT (t->expiration_time >= tw->current_tick);
452 interval = t->expiration_time - tw->current_tick;
454 /* Right back onto the overflow vector? */
455 if (interval >= (1 << (3 * TW_RING_SHIFT)))
458 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
461 /* Compute ring offsets */
462 new_glacier_ring_offset = interval >> (2 * TW_RING_SHIFT);
464 interval -= (new_glacier_ring_offset << (2 * TW_RING_SHIFT));
466 /* Note: the wheels are at (0,0,0), no add-with-carry needed */
467 new_slow_ring_offset = interval >> TW_RING_SHIFT;
468 interval -= (new_slow_ring_offset << TW_RING_SHIFT);
469 new_fast_ring_offset = interval & TW_RING_MASK;
470 t->slow_ring_offset = new_slow_ring_offset;
471 t->fast_ring_offset = new_fast_ring_offset;
473 /* Timer expires Right Now */
474 if (PREDICT_FALSE (t->slow_ring_offset == 0 &&
475 t->fast_ring_offset == 0 &&
476 new_glacier_ring_offset == 0))
478 vec_add1 (callback_vector, t->user_handle);
479 pool_put (tw->timers, t);
481 /* Timer moves to the glacier ring */
482 else if (new_glacier_ring_offset)
484 ts = &tw->w[TW_TIMER_RING_GLACIER][new_glacier_ring_offset];
485 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
487 /* Timer moves to the slow ring */
488 else if (t->slow_ring_offset)
490 /* Add to slow ring */
491 ts = &tw->w[TW_TIMER_RING_SLOW][t->slow_ring_offset];
492 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
494 /* Timer timer moves to the fast ring */
497 ts = &tw->w[TW_TIMER_RING_FAST][t->fast_ring_offset];
498 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
499 #if TW_FAST_WHEEL_BITMAP
500 tw->fast_slot_bitmap =
501 clib_bitmap_set (tw->fast_slot_bitmap,
502 t->fast_ring_offset, 1);
509 #if TW_TIMER_WHEELS > 2
511 * Double odometer-click? Process one slot in the glacier ring...
513 if (PREDICT_FALSE (fast_wheel_index == TW_SLOTS_PER_RING
514 && slow_wheel_index == TW_SLOTS_PER_RING))
516 glacier_wheel_index %= TW_SLOTS_PER_RING;
517 ts = &tw->w[TW_TIMER_RING_GLACIER][glacier_wheel_index];
519 head = pool_elt_at_index (tw->timers, ts->head_index);
520 next_index = head->next;
522 /* Make slot empty */
523 head->next = head->prev = ts->head_index;
525 /* traverse slot, deal timers into slow ring */
526 while (next_index != head - tw->timers)
528 t = pool_elt_at_index (tw->timers, next_index);
529 next_index = t->next;
531 /* Remove from glacier ring slot (hammer) */
532 t->next = t->prev = ~0;
534 /* Timer expires Right Now */
535 if (PREDICT_FALSE (t->slow_ring_offset == 0 &&
536 t->fast_ring_offset == 0))
538 vec_add1 (callback_vector, t->user_handle);
539 pool_put (tw->timers, t);
541 /* Timer expires during slow-wheel tick 0 */
542 else if (PREDICT_FALSE (t->slow_ring_offset == 0))
544 ts = &tw->w[TW_TIMER_RING_FAST][t->fast_ring_offset];
545 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
546 #if TW_FAST_WHEEL_BITMAP
547 tw->fast_slot_bitmap =
548 clib_bitmap_set (tw->fast_slot_bitmap,
549 t->fast_ring_offset, 1);
552 else /* typical case */
554 /* Add to slow ring */
555 ts = &tw->w[TW_TIMER_RING_SLOW][t->slow_ring_offset];
556 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
562 #if TW_TIMER_WHEELS > 1
564 * Single odometer-click? Process a slot in the slow ring,
566 if (PREDICT_FALSE (fast_wheel_index == TW_SLOTS_PER_RING))
568 slow_wheel_index %= TW_SLOTS_PER_RING;
569 ts = &tw->w[TW_TIMER_RING_SLOW][slow_wheel_index];
571 head = pool_elt_at_index (tw->timers, ts->head_index);
572 next_index = head->next;
574 /* Make slot empty */
575 head->next = head->prev = ts->head_index;
577 /* traverse slot, deal timers into fast ring */
578 while (next_index != head - tw->timers)
580 t = pool_elt_at_index (tw->timers, next_index);
581 next_index = t->next;
583 /* Remove from sloe ring slot (hammer) */
584 t->next = t->prev = ~0;
586 /* Timer expires Right Now */
587 if (PREDICT_FALSE (t->fast_ring_offset == 0))
589 vec_add1 (callback_vector, t->user_handle);
590 pool_put (tw->timers, t);
592 else /* typical case */
594 /* Add to fast ring */
595 ts = &tw->w[TW_TIMER_RING_FAST][t->fast_ring_offset];
596 timer_addhead (tw->timers, ts->head_index, t - tw->timers);
597 #if TW_FAST_WHEEL_BITMAP
598 tw->fast_slot_bitmap =
599 clib_bitmap_set (tw->fast_slot_bitmap,
600 t->fast_ring_offset, 1);
607 /* Handle the fast ring */
608 fast_wheel_index %= TW_SLOTS_PER_RING;
609 ts = &tw->w[TW_TIMER_RING_FAST][fast_wheel_index];
611 head = pool_elt_at_index (tw->timers, ts->head_index);
612 next_index = head->next;
614 /* Make slot empty */
615 head->next = head->prev = ts->head_index;
617 /* Construct vector of expired timer handles to give the user */
618 while (next_index != ts->head_index)
620 t = pool_elt_at_index (tw->timers, next_index);
621 next_index = t->next;
622 vec_add1 (callback_vector, t->user_handle);
623 pool_put (tw->timers, t);
626 /* If any timers expired, tell the user */
627 if (callback_vector_arg == 0 && vec_len (callback_vector))
629 /* The callback is optional. We return the u32 * handle vector */
630 if (tw->expired_timer_callback)
632 tw->expired_timer_callback (callback_vector);
633 _vec_len (callback_vector) = 0;
635 tw->expired_timer_handles = callback_vector;
638 #if TW_FAST_WHEEL_BITMAP
639 tw->fast_slot_bitmap = clib_bitmap_set (tw->fast_slot_bitmap,
640 fast_wheel_index, 0);
645 tw->current_index[TW_TIMER_RING_FAST] = fast_wheel_index;
647 #if TW_TIMER_WHEELS > 1
648 if (PREDICT_FALSE (fast_wheel_index == TW_SLOTS_PER_RING))
650 tw->current_index[TW_TIMER_RING_SLOW] = slow_wheel_index;
653 #if TW_TIMER_WHEELS > 2
654 if (PREDICT_FALSE (slow_wheel_index == TW_SLOTS_PER_RING))
655 glacier_wheel_index++;
656 tw->current_index[TW_TIMER_RING_GLACIER] = glacier_wheel_index;
659 if (vec_len (callback_vector) >= tw->max_expirations)
663 if (callback_vector_arg == 0)
664 tw->expired_timer_handles = callback_vector;
666 tw->last_run_time += i * tw->timer_interval;
667 return callback_vector;
670 u32 *TW (tw_timer_expire_timers) (TWT (tw_timer_wheel) * tw, f64 now)
672 return TW (tw_timer_expire_timers_internal) (tw, now, 0 /* no vector */ );
675 u32 *TW (tw_timer_expire_timers_vec) (TWT (tw_timer_wheel) * tw, f64 now,
678 return TW (tw_timer_expire_timers_internal) (tw, now, vec);
681 #if TW_FAST_WHEEL_BITMAP
682 /** Returns an approximation to the first timer expiration in
683 * timer-ticks from "now". To avoid wasting an unjustifiable
684 * amount of time on the problem, we maintain an approximate fast-wheel slot
685 * occupancy bitmap. We don't worry about clearing fast wheel bits
686 * when timers are removed from fast wheel slots.
689 u32 TW (tw_timer_first_expires_in_ticks) (TWT (tw_timer_wheel) * tw)
691 u32 first_expiring_index, fast_ring_index;
694 if (clib_bitmap_is_zero (tw->fast_slot_bitmap))
695 return TW_SLOTS_PER_RING;
697 fast_ring_index = tw->current_index[TW_TIMER_RING_FAST];
698 if (fast_ring_index == TW_SLOTS_PER_RING)
701 first_expiring_index = clib_bitmap_next_set (tw->fast_slot_bitmap,
703 if (first_expiring_index == ~0 && fast_ring_index != 0)
704 first_expiring_index = clib_bitmap_first_set (tw->fast_slot_bitmap);
706 ASSERT (first_expiring_index != ~0);
708 delta = (i32) first_expiring_index - (i32) fast_ring_index;
710 delta += TW_SLOTS_PER_RING;
720 * fd.io coding-style-patch-verification: ON
723 * eval: (c-set-style "gnu")