frsh_hash_table.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 FRESCOR consortium partners:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politécnica  Valencia,           SPAIN
   9 //    Czech Technical University in Prague,  CZECH REPUBLIC
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  18 //           FRESCOR project (FP6/2005/IST/5-034026) is funded
  19 //        in part by the European Union Sixth Framework Programme
  20 //        The European Union is not liable of any use that may be
  21 //        made of this code.
  22 //
  23 //
  24 //  This file is part of FRSH Implementation
  25 //
  26 //  FRSH API is free software; you can  redistribute it and/or  modify
  27 //  it under the terms of  the GNU General Public License as published by
  28 //  the Free Software Foundation;  either  version 2, or (at  your option)
  29 //  any later version.
  30 //
  31 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  32 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  33 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  34 //  General Public License for more details.
  35 //
  36 //  You should have  received a  copy of  the  GNU  General Public License
  37 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  38 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  39 //  02111-1307, USA.
  40 //
  41 //  As a special exception, if you include this header file into source
  42 //  files to be compiled, this header file does not by itself cause
  43 //  the resulting executable to be covered by the GNU General Public
  44 //  License.  This exception does not however invalidate any other
  45 //  reasons why the executable file might be covered by the GNU General
  46 //  Public License.
  47 // -----------------------------------------------------------------------
  48 //==============================================
  49 //  ******** *******    ********  **      **
  50 //  **///// /**////**  **//////  /**     /**
  51 //  **      /**   /** /**        /**     /**
  52 //  ******* /*******  /********* /**********
  53 //  **////  /**///**  ////////** /**//////**
  54 //  **      /**  //**        /** /**     /**
  55 //  **      /**   //** ********  /**     /**
  56 //  //       //     // ////////   //      //
  57 //
  58 // FRSH(FRescor ScHeduler), pronounced "fresh"
  59 //==============================================
  60 //
  61
  62 // This header file defines the interface to a hash table used to map
  63 // from a string key into an integer value. The number of entries in
  64 // the hash table is bounded by a maximum value, and therefore it is
  65 // not necessary to have a dynamic size table. The integer values are
  66 // non negative, so a negative value can be used as an error
  67 // indication. The key strings are assumed constant, so there is no
  68 // need to copy them.
  69
  70
  71 #ifndef FRSH_HASH_TABLE
  72 #define FRSH_HASH_TABLE
  73
  74 #include <stdbool.h>
  75
  76 /**
  77  * A configurable constant that defines the maximum length of the string keys
  78  */
  79
  80 #define FRSH_HASH_TABLE_MAX_CHARS 21
  81
  82 // Type that contains the status of an entry
  83 typedef enum {frsh_hash_empty, frsh_hash_valid, frsh_hash_cleaned}
  84 frsh_hash_entry_status_t;
  85
  86 /**
  87  * Type that defines a table entry
  88  */
  89 typedef struct {
  90   char key[FRSH_HASH_TABLE_MAX_CHARS]; // array where the key is stored
  91   unsigned int value;                  // unsigned integer value
  92   frsh_hash_entry_status_t status;     // indicates the entry status
  93 } frsh_hash_entry_t;
  94
  95 /**
  96  * Type that defines a hash table
  97  */
  98 typedef struct {
  99   int size;                      // size of the table
 100   int max_chars;                 // maximum characters of the key strings
 101   int num;                       // current number of entries
 102   int cleaned;                   // current number of cleaned entries
 103   frsh_hash_entry_t * entry;     // pointer to table of entries
 104   frsh_hash_entry_t * old_entry; // pointer to old table of entries, used
 105                                  // to recreate the table when necessary
 106 } frsh_hash_table_t;
 107
 108 /**
 109  * Function that maps a string key into an integer value
 110  */
 111 unsigned int frsh_hash_function (const char *str, int max_chars);
 112
 113
 114 /**
 115  * Create a hash table to store up to the specified number of
 116  * keys equal to max_size. The maximum size of the String values
 117  * is specified in max_chars.
 118  * Returns: 0 if successful
 119  *          FRSH_ERR_NO_SPACE if there is not enough memory available
 120  *          FRSH_ERR_TOO_LARGE if max_chars exceeds FRSH_HASH_TABLE_MAX_CHARS
 121  */
 122 int frsh_hash_table_init (frsh_hash_table_t *table,
 123                           int max_size, int max_chars);
 124
 125 /**
 126  * Delete a hash table, eliminating the resources allocated to it
 127  */
 128 void frsh_hash_table_destroy (frsh_hash_table_t *table);
 129
 130 /**
 131  * Empty a hash table, eliminating all entries from it
 132  */
 133 void frsh_hash_table_clean (frsh_hash_table_t *table);
 134
 135 /**
 136  * Assign a value to a key. An older value is removed if present
 137  * Returns: 0 if successful
 138  *          FRSH_ERR_NO_SPACE if the maximum number of keys would be exceeded
 139  */
 140 int frsh_hash_table_put (frsh_hash_table_t *table,
 141                          const char * key, unsigned int value);
 142
 143 /**
 144  * Get the value assigned to a key.
 145  * Returns 0 if successful or -1 if the key is not present
 146  */
 147 int frsh_hash_table_get (frsh_hash_table_t *table,
 148                          const char * key, unsigned int * value);
 149
 150 /**
 151  * Indicate whether or not the specified key is contained in the table
 152  */
 153 bool frsh_hash_table_contains_key (frsh_hash_table_t *table, const char * key);
 154
 155 /**
 156  * Remove an entry from the table given a key
 157  * Returns 0 if successful, or -1 if the key is not contained in the table
 158  */
 159 int frsh_hash_table_remove (frsh_hash_table_t *table, const char * key);
 160
 161
 162 #endif // FRSH_HASH_TABLE
 163
 164
 165