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