ipc/generic_hash.h

   1 /***************************************************************************
   2  * Copyright 1995    Michael Veksler. mveksler@vnet.ibm.com
   3  ***************************************************************************
   4  * File:      generic_hash.h
   5  * Purpose :  dynamically growing hash, may use shared or local memory.
   6  ***************************************************************************
   7  */
   8 #ifndef _GENERIC_HASH_H_
   9 #define _GENERIC_HASH_H_
  10
  11 #include "wintypes.h"
  12 #include "shm_block.h"
  13 /* default hash values */
  14 #define HASH_LOAD           70
  15 #define HASH_MEM_ALLOC      (HASH_PTR (*)(int size)) malloc
  16 #define HASH_MEM_FREE       (void (*)(HASH_PTR)) free
  17 #define HASH_MEM_ACCESS     access_local_hash
  18 #define HASH_REALLOC_JUMPS  1.5  /* Relative size of the new memory */
  19 #define MIN_HASH            13
  20
  21 typedef union {
  22     char string[1];
  23     WORD words[1];
  24     DWORD dwords[1];
  25     char *ptr;
  26     SEGPTR segptr;
  27 } HASH_VAL;
  28
  29 typedef struct hash_item_struct {
  30     DWORD key;
  31     HASH_VAL data;
  32 } HASH_ITEM;
  33
  34 /* point to the hash structure */
  35 typedef union {
  36     HASH_ITEM* ptr;             /* Local pointer */
  37     REL_PTR    rel;                     /* IPC relative address */
  38     SEGPTR segptr;              /* Universal (can be IPC or local) */
  39 } HASH_PTR;
  40
  41 typedef struct hash_share_struct {
  42     int total_items;            /* total number of items (array size) */
  43     int free_items;             /* number of free items (excluding deleted) */
  44     int deleted_items;          /* number of deleted items */
  45     int ptr_updates;            /* Number of updates to `items' pointer */
  46                                 /* (of items) - used for intecepting */
  47                                 /* changes to the pointer. */
  48     HASH_PTR items;             /* pointer to the items */
  49 } HASH_SHARED;
  50 typedef BOOL HASH_ITEM_TEST(HASH_VAL *value, HASH_VAL *seeked_data);
  51
  52 /* NOTE:
  53  * 1. Keys 0 and -1 are reserved.
  54  * 2. none of these items should be accessed directly, use existing
  55  *    functions. If they are not enough, add a new function.
  56  */
  57 typedef struct hash_container_struct {
  58     int bytes_per_item;
  59     int maximum_load;           /* in percents (0..100) default is 70 */
  60     int min_free_items;         /* minimum free items before reallocating
  61                                    (Function of maximum_load) */
  62
  63     int last_ptr_update;        /* to be compared with shared.ptr_updates */
  64     BOOL shared_was_malloced;   /* Need that to know how to destroy hash */
  65
  66     /* This is an optional handler.
  67      * If not NULL, this function is used for distinguishing between
  68      * different data with the same key (key field holds integer and
  69      * is too short for long keys like strings).
  70      */
  71     HASH_ITEM_TEST *is_correct_item;
  72
  73     /* Handlers used for reallocating memory
  74      * [by allocating new data and then freeing old data]
  75      */
  76     HASH_PTR (*allocate_mem)(int size);
  77     void     (*free_mem)(HASH_PTR);
  78
  79     /* Translator from HASH_PTR construct to a regular pointer.
  80        use HASH_MEM_ACCESS, if no translation is needed */
  81     HASH_ITEM *(*access_mem)(HASH_PTR);
  82
  83     HASH_ITEM *items;
  84     HASH_SHARED *shared;        /* Things to be on shared memory. */
  85 } HASH_CONTAINER;
  86
  87
  88 /********** Hash maintenance functions ***********/
  89
  90
  91
  92 /* Attach existing & running remote (i.e. shared) hash.
  93  * Attach the items using the data stored in "shared"
  94  */
  95 HASH_CONTAINER *attach_remote_hash(HASH_SHARED *shared, int bytes_per_datum,
  96                                    HASH_ITEM *(*access_mem)(HASH_PTR));
  97
  98
  99 HASH_CONTAINER *create_remote_hash(HASH_SHARED *shared,
 100                                    int bytes_per_datum,
 101                                    int total_items,
 102                                    HASH_PTR (*allocate_mem)(int size),
 103                                    HASH_ITEM *(*access_mem)(HASH_PTR));
 104 /* hash constructor: create brand new hash (not on shared memory) */
 105 HASH_CONTAINER *create_hash(int bytes_per_datum, int total_items);
 106
 107 /* set the extra handlers to non default values */
 108 void set_hash_handlers(HASH_CONTAINER *hash,
 109                        HASH_ITEM_TEST *is_correct_item,
 110                        HASH_PTR (*allocate_mem)(int size),
 111                        void     (*free_mem)(HASH_PTR),
 112                        HASH_ITEM *(*access_mem)(HASH_PTR));
 113
 114 /* set extra parameters */
 115 void set_hash_parameters(HASH_CONTAINER *hash, int load);
 116
 117 /* hash destructors */
 118 void destroy_hash(HASH_CONTAINER *hash);
 119 void detach_hash(HASH_CONTAINER *hash);
 120
 121
 122 /********** Hash usage *************/
 123
 124 /* All following functions have the same format:
 125  *  hash- the hash structure to use
 126  *  key-  used as primary means to get to the entry.
 127  *  data- 1. a secondary key (used only if `is_correct_item' is set).
 128  *        2. data to store. (for hash_add_item).
 129  */
 130 HASH_VAL *hash_locate_item(HASH_CONTAINER* hash,int key, HASH_VAL* seeked_data);
 131 BOOL hash_add_item(HASH_CONTAINER*        hash, int key, HASH_VAL* data);
 132 BOOL hash_delete_item(HASH_CONTAINER*     hash, int key, HASH_VAL* seeked_data);
 133
 134
 135 void *ret_null();               /* function returning null (used for */
 136                                 /* disabling memory reallocation) */
 137
 138 /* access function used by local (non IPC) memory */
 139 HASH_ITEM *access_local_hash(HASH_PTR ptr);
 140
 141 #endif /* _GENERIC_HASH_H_ */