ctdb/common/hash_count.h

   1 /*
   2    Using hash table for counting events
   3
   4    Copyright (C) Amitay Isaacs  2017
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_HASH_COUNT_H__
  21 #define __CTDB_HASH_COUNT_H__
  22
  23 /**
  24  * @file hash_count.h
  25  *
  26  * @brief Count key-based events for specified interval
  27  *
  28  * This can be used to measure the rate of events based on any interval.
  29  * For example, number of occurrences per second.
  30  */
  31
  32 /**
  33  * @brief Handler callback function called when counter is incremented
  34  *
  35  * This function is called every time a counter is incremented for a key.
  36  * The counter argument is the number of times the increment function is
  37  * called during a count interval.
  38  *
  39  * This function should not modify key and data arguments.
  40  */
  41 typedef void (*hash_count_update_handler_fn)(TDB_DATA key, uint64_t counter,
  42                                              void *private_data);
  43
  44 /**
  45  * @brief Abstract structure representing hash based counting
  46  */
  47 struct hash_count_context;
  48
  49 /**
  50  * @brief Initialize hash counting
  51  *
  52  * This return a new hash count context which is a talloc context.  Freeing
  53  * this context will free all the memory associated with hash count.
  54  *
  55  * @param[in] mem_ctx Talloc memory context
  56  * @param[in] count_interval The time interval for counting events
  57  * @param[in] handler Function called when counter is incremented
  58  * @param[in] private_data Private data to handler function
  59  * @param[out] result The new hash_count structure
  60  * @return 0 on success, errno on failure
  61  */
  62 int hash_count_init(TALLOC_CTX *mem_ctx, struct timeval count_interval,
  63                     hash_count_update_handler_fn handler, void *private_data,
  64                     struct hash_count_context **result);
  65
  66 /**
  67  * @brief Increment a counter for a key
  68  *
  69  * First time this is called for a key, corresponding counter is set to 1
  70  * and the start time is noted.  For all subsequent calls made during the
  71  * count_interval (used in initializing the context) will increment
  72  * corresponding counter for the key.  After the count_interval has elapsed,
  73  * the counter will be reset to 1.
  74  *
  75  * @param[in] hcount The hash count context
  76  * @param[in] key The key for which counter is updated
  77  * @return 0 on success, errno on failure
  78  *
  79  * This will result in a callback function being called.
  80  */
  81 int hash_count_increment(struct hash_count_context *hcount, TDB_DATA key);
  82
  83 /**
  84  * @brief Remove keys for which count interval has elapsed
  85  *
  86  * This function is used to clean the database of keys for which there are
  87  * no recent events.
  88  *
  89  * @param[in] hcount The hash count context
  90  * @param[out] delete_count The number of keys deleted
  91  */
  92 void hash_count_expire(struct hash_count_context *hcount, int *delete_count);
  93
  94 #endif /* __CTDB_HASH_COUNT_H__ */