filters/rate/bucket.h

   1 /* nbdkit
   2  * Copyright (C) 2018-2020 Red Hat Inc.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met:
   7  *
   8  * * Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *
  11  * * Redistributions in binary form must reproduce the above copyright
  12  * notice, this list of conditions and the following disclaimer in the
  13  * documentation and/or other materials provided with the distribution.
  14  *
  15  * * Neither the name of Red Hat nor the names of its contributors may be
  16  * used to endorse or promote products derived from this software without
  17  * specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
  20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  21  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  22  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
  23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  26  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  27  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30  * SUCH DAMAGE.
  31  */
  32
  33 #ifndef NBDKIT_BUCKET_H
  34 #define NBDKIT_BUCKET_H
  35
  36 #include <stdint.h>
  37 #include <time.h>
  38 #include <sys/time.h>
  39
  40 /* A token bucket. */
  41 struct bucket {
  42   uint64_t rate;                /* Fill rate.  0 = no limit set. */
  43   double capacity_secs;         /* Capacity as supplied to bucket_init. */
  44   uint64_t capacity;            /* Maximum capacity of the bucket in tokens. */
  45   uint64_t level;               /* How full is the bucket now? */
  46   struct timeval tv;            /* Last time we updated the level. */
  47 };
  48
  49 /* Initialize the bucket structure.  Capacity is expressed in
  50  * rate-equivalent seconds.
  51  */
  52 extern void bucket_init (struct bucket *bucket,
  53                          uint64_t rate, double capacity_secs);
  54
  55 /* Dynamically adjust the rate.  The old rate is returned. */
  56 extern uint64_t bucket_adjust_rate (struct bucket *bucket, uint64_t rate);
  57
  58 /* Take up to N tokens from the bucket.
  59  *
  60  * If the bucket has >= N tokens (ie. we can send the packet now) then
  61  * the number of tokens in the bucket is reduced by N and this
  62  * function returns 0.  (Note: *TS is _not_ initialized in this case
  63  * because the caller should not sleep).
  64  *
  65  * If the bucket has fewer than N tokens then the bucket is emptied
  66  * and the number of tokens we still need to take is returned as a
  67  * positive number > 0.  In this case, *TS is initialized with the
  68  * estimated length of time you should sleep.
  69  *
  70  * In the case where the caller needs to sleep, it must make a further
  71  * call to bucket_run before proceeding, since another thread may have
  72  * "stolen" the tokens while you were sleeping.
  73  */
  74 extern uint64_t bucket_run (struct bucket *bucket, const char *bucket_name,
  75                             uint64_t n, struct timespec *ts);
  76
  77 #endif /* NBDKIT_BUCKET_H */