LCOV - code coverage report
Current view: top level - girepository/cmph - chm.c (source / functions) Coverage Total Hit
Test: unnamed Lines: 7.2 % 209 15
Test Date: 2024-11-26 05:23:01 Functions: 15.4 % 13 2
Branches: - 0 0

             Branch data     Line data    Source code
       1                 :             : #include "graph.h"
       2                 :             : #include "chm.h"
       3                 :             : #include "cmph_structs.h"
       4                 :             : #include "chm_structs.h"
       5                 :             : #include "hash.h"
       6                 :             : #include "bitbool.h"
       7                 :             : 
       8                 :             : #include <math.h>
       9                 :             : #include <stdlib.h>
      10                 :             : #include <stdio.h>
      11                 :             : #include <assert.h>
      12                 :             : #include <string.h>
      13                 :             : #include <errno.h>
      14                 :             : 
      15                 :             : //#define DEBUG
      16                 :             : #include "debug.h"
      17                 :             : 
      18                 :             : static int chm_gen_edges(cmph_config_t *mph);
      19                 :             : static void chm_traverse(chm_config_data_t *chm, cmph_uint8 *visited, cmph_uint32 v);
      20                 :             : 
      21                 :          10 : chm_config_data_t *chm_config_new(void)
      22                 :             : {
      23                 :          10 :         chm_config_data_t *chm = NULL;
      24                 :          10 :         chm = (chm_config_data_t *)malloc(sizeof(chm_config_data_t));
      25                 :          10 :         assert(chm);
      26                 :          10 :         memset(chm, 0, sizeof(chm_config_data_t));
      27                 :          10 :         chm->hashfuncs[0] = CMPH_HASH_JENKINS;
      28                 :          10 :         chm->hashfuncs[1] = CMPH_HASH_JENKINS;
      29                 :          10 :         chm->g = NULL;
      30                 :          10 :         chm->graph = NULL;
      31                 :          10 :         chm->hashes = NULL;
      32                 :          10 :         return chm;
      33                 :             : }
      34                 :          10 : void chm_config_destroy(cmph_config_t *mph)
      35                 :             : {
      36                 :          10 :         chm_config_data_t *data = (chm_config_data_t *)mph->data;
      37                 :             :         DEBUGP("Destroying algorithm dependent data\n");
      38                 :          10 :         free(data);
      39                 :          10 : }
      40                 :             : 
      41                 :           0 : void chm_config_set_hashfuncs(cmph_config_t *mph, CMPH_HASH *hashfuncs)
      42                 :             : {
      43                 :           0 :         chm_config_data_t *chm = (chm_config_data_t *)mph->data;
      44                 :           0 :         CMPH_HASH *hashptr = hashfuncs;
      45                 :           0 :         cmph_uint32 i = 0;
      46                 :           0 :         while(*hashptr != CMPH_HASH_COUNT)
      47                 :             :         {
      48                 :           0 :                 if (i >= 2) break; //chm only uses two hash functions
      49                 :           0 :                 chm->hashfuncs[i] = *hashptr;        
      50                 :           0 :                 ++i, ++hashptr;
      51                 :             :         }
      52                 :           0 : }
      53                 :             : 
      54                 :           0 : cmph_t *chm_new(cmph_config_t *mph, double c)
      55                 :             : {
      56                 :           0 :         cmph_t *mphf = NULL;
      57                 :           0 :         chm_data_t *chmf = NULL;
      58                 :             : 
      59                 :             :         cmph_uint32 i;
      60                 :           0 :         cmph_uint32 iterations = 20;
      61                 :           0 :         cmph_uint8 *visited = NULL;
      62                 :           0 :         chm_config_data_t *chm = (chm_config_data_t *)mph->data;
      63                 :           0 :         chm->m = mph->key_source->nkeys;
      64                 :           0 :         if (c == 0) c = 2.09;
      65                 :           0 :         chm->n = (cmph_uint32)ceil(c * mph->key_source->nkeys);        
      66                 :             :         DEBUGP("m (edges): %u n (vertices): %u c: %f\n", chm->m, chm->n, c);
      67                 :           0 :         chm->graph = graph_new(chm->n, chm->m);
      68                 :             :         DEBUGP("Created graph\n");
      69                 :             : 
      70                 :           0 :         chm->hashes = (hash_state_t **)malloc(sizeof(hash_state_t *)*3);
      71                 :           0 :         for(i = 0; i < 3; ++i) chm->hashes[i] = NULL;
      72                 :             :         //Mapping step
      73                 :           0 :         if (mph->verbosity)
      74                 :             :         {
      75                 :           0 :                 fprintf(stderr, "Entering mapping step for mph creation of %u keys with graph sized %u\n", chm->m, chm->n);
      76                 :             :         }
      77                 :             :         while(1)
      78                 :           0 :         {
      79                 :             :                 int ok;
      80                 :           0 :                 chm->hashes[0] = hash_state_new(chm->hashfuncs[0], chm->n);
      81                 :           0 :                 chm->hashes[1] = hash_state_new(chm->hashfuncs[1], chm->n);
      82                 :           0 :                 ok = chm_gen_edges(mph);
      83                 :           0 :                 if (!ok)
      84                 :             :                 {
      85                 :           0 :                         --iterations;
      86                 :           0 :                         hash_state_destroy(chm->hashes[0]);
      87                 :           0 :                         chm->hashes[0] = NULL;
      88                 :           0 :                         hash_state_destroy(chm->hashes[1]);
      89                 :           0 :                         chm->hashes[1] = NULL;
      90                 :             :                         DEBUGP("%u iterations remaining\n", iterations);
      91                 :           0 :                         if (mph->verbosity)
      92                 :             :                         {
      93                 :           0 :                                 fprintf(stderr, "Acyclic graph creation failure - %u iterations remaining\n", iterations);
      94                 :             :                         }
      95                 :           0 :                         if (iterations == 0) break;
      96                 :             :                 } 
      97                 :           0 :                 else break;     
      98                 :             :         }
      99                 :           0 :         if (iterations == 0)
     100                 :             :         {
     101                 :           0 :                 graph_destroy(chm->graph);   
     102                 :           0 :                 return NULL;
     103                 :             :         }
     104                 :             : 
     105                 :             :         //Assignment step
     106                 :           0 :         if (mph->verbosity)
     107                 :             :         {
     108                 :           0 :                 fprintf(stderr, "Starting assignment step\n");
     109                 :             :         }
     110                 :             :         DEBUGP("Assignment step\n");
     111                 :           0 :         visited = (cmph_uint8 *)malloc((size_t)(chm->n/8 + 1));
     112                 :           0 :         memset(visited, 0, (size_t)(chm->n/8 + 1));
     113                 :           0 :         free(chm->g);
     114                 :           0 :         chm->g = (cmph_uint32 *)malloc(chm->n * sizeof(cmph_uint32));
     115                 :           0 :         assert(chm->g);
     116                 :           0 :         for (i = 0; i < chm->n; ++i)
     117                 :             :         {
     118                 :           0 :                 if (!GETBIT(visited,i))
     119                 :             :                 {
     120                 :           0 :                         chm->g[i] = 0;
     121                 :           0 :                         chm_traverse(chm, visited, i);
     122                 :             :                 }
     123                 :             :         }
     124                 :           0 :         graph_destroy(chm->graph);   
     125                 :           0 :         free(visited);
     126                 :           0 :         chm->graph = NULL;
     127                 :             : 
     128                 :           0 :         mphf = (cmph_t *)malloc(sizeof(cmph_t));
     129                 :           0 :         mphf->algo = mph->algo;
     130                 :           0 :         chmf = (chm_data_t *)malloc(sizeof(chm_data_t));
     131                 :           0 :         chmf->g = chm->g;
     132                 :           0 :         chm->g = NULL; //transfer memory ownership
     133                 :           0 :         chmf->hashes = chm->hashes;
     134                 :           0 :         chm->hashes = NULL; //transfer memory ownership
     135                 :           0 :         chmf->n = chm->n;
     136                 :           0 :         chmf->m = chm->m;
     137                 :           0 :         mphf->data = chmf;
     138                 :           0 :         mphf->size = chm->m;
     139                 :             :         DEBUGP("Successfully generated minimal perfect hash\n");
     140                 :           0 :         if (mph->verbosity)
     141                 :             :         {
     142                 :           0 :                 fprintf(stderr, "Successfully generated minimal perfect hash function\n");
     143                 :             :         }
     144                 :           0 :         return mphf;
     145                 :             : }
     146                 :             : 
     147                 :           0 : static void chm_traverse(chm_config_data_t *chm, cmph_uint8 *visited, cmph_uint32 v)
     148                 :             : {
     149                 :             : 
     150                 :           0 :         graph_iterator_t it = graph_neighbors_it(chm->graph, v);
     151                 :           0 :         cmph_uint32 neighbor = 0;
     152                 :           0 :         SETBIT(visited,v);
     153                 :             :         
     154                 :             :         DEBUGP("Visiting vertex %u\n", v);
     155                 :           0 :         while((neighbor = graph_next_neighbor(chm->graph, &it)) != GRAPH_NO_NEIGHBOR)
     156                 :             :         {
     157                 :             :                 DEBUGP("Visiting neighbor %u\n", neighbor);
     158                 :           0 :                 if(GETBIT(visited,neighbor)) continue;
     159                 :             :                 DEBUGP("Visiting neighbor %u\n", neighbor);
     160                 :             :                 DEBUGP("Visiting edge %u->%u with id %u\n", v, neighbor, graph_edge_id(chm->graph, v, neighbor));
     161                 :           0 :                 chm->g[neighbor] = graph_edge_id(chm->graph, v, neighbor) - chm->g[v];
     162                 :             :                 DEBUGP("g is %u (%u - %u mod %u)\n", chm->g[neighbor], graph_edge_id(chm->graph, v, neighbor), chm->g[v], chm->m);
     163                 :           0 :                 chm_traverse(chm, visited, neighbor);
     164                 :             :         }
     165                 :           0 : }
     166                 :             :                 
     167                 :           0 : static int chm_gen_edges(cmph_config_t *mph)
     168                 :             : {
     169                 :             :         cmph_uint32 e;
     170                 :           0 :         chm_config_data_t *chm = (chm_config_data_t *)mph->data;
     171                 :           0 :         int cycles = 0;
     172                 :             : 
     173                 :             :         DEBUGP("Generating edges for %u vertices with hash functions %s and %s\n", chm->n, cmph_hash_names[chm->hashfuncs[0]], cmph_hash_names[chm->hashfuncs[1]]);
     174                 :           0 :         graph_clear_edges(chm->graph);       
     175                 :           0 :         mph->key_source->rewind(mph->key_source->data);
     176                 :           0 :         for (e = 0; e < mph->key_source->nkeys; ++e)
     177                 :             :         {
     178                 :             :                 cmph_uint32 h1, h2;
     179                 :             :                 cmph_uint32 keylen;
     180                 :             :                 char *key;
     181                 :           0 :                 mph->key_source->read(mph->key_source->data, &key, &keylen);
     182                 :           0 :                 h1 = hash(chm->hashes[0], key, keylen) % chm->n;
     183                 :           0 :                 h2 = hash(chm->hashes[1], key, keylen) % chm->n;
     184                 :           0 :                 if (h1 == h2) if (++h2 >= chm->n) h2 = 0;
     185                 :           0 :                 if (h1 == h2) 
     186                 :             :                 {
     187                 :           0 :                         if (mph->verbosity) fprintf(stderr, "Self loop for key %u\n", e);
     188                 :           0 :                         mph->key_source->dispose(mph->key_source->data, key, keylen);
     189                 :           0 :                         return 0;
     190                 :             :                 }
     191                 :             :                 DEBUGP("Adding edge: %u -> %u for key %s\n", h1, h2, key);
     192                 :           0 :                 mph->key_source->dispose(mph->key_source->data, key, keylen);
     193                 :           0 :                 graph_add_edge(chm->graph, h1, h2);
     194                 :             :         }
     195                 :           0 :         cycles = graph_is_cyclic(chm->graph);
     196                 :           0 :         if (mph->verbosity && cycles) fprintf(stderr, "Cyclic graph generated\n");
     197                 :             :         DEBUGP("Looking for cycles: %u\n", cycles);
     198                 :             : 
     199                 :           0 :         return ! cycles;
     200                 :             : }
     201                 :             : 
     202                 :           0 : int chm_dump(cmph_t *mphf, FILE *fd)
     203                 :             : {
     204                 :           0 :         char *buf = NULL;
     205                 :             :         cmph_uint32 buflen;
     206                 :           0 :         cmph_uint32 two = 2; //number of hash functions
     207                 :           0 :         chm_data_t *data = (chm_data_t *)mphf->data;
     208                 :             :         register size_t nbytes;
     209                 :             :         
     210                 :           0 :         __cmph_dump(mphf, fd);
     211                 :             : 
     212                 :           0 :         nbytes = fwrite(&two, sizeof(cmph_uint32), (size_t)1, fd);
     213                 :           0 :         hash_state_dump(data->hashes[0], &buf, &buflen);
     214                 :             :         DEBUGP("Dumping hash state with %u bytes to disk\n", buflen);
     215                 :           0 :         nbytes = fwrite(&buflen, sizeof(cmph_uint32), (size_t)1, fd);
     216                 :           0 :         nbytes = fwrite(buf, (size_t)buflen, (size_t)1, fd);
     217                 :           0 :         free(buf);
     218                 :             : 
     219                 :           0 :         hash_state_dump(data->hashes[1], &buf, &buflen);
     220                 :             :         DEBUGP("Dumping hash state with %u bytes to disk\n", buflen);
     221                 :           0 :         nbytes = fwrite(&buflen, sizeof(cmph_uint32), (size_t)1, fd);
     222                 :           0 :         nbytes = fwrite(buf, (size_t)buflen, (size_t)1, fd);
     223                 :           0 :         free(buf);
     224                 :             : 
     225                 :           0 :         nbytes = fwrite(&(data->n), sizeof(cmph_uint32), (size_t)1, fd);
     226                 :           0 :         nbytes = fwrite(&(data->m), sizeof(cmph_uint32), (size_t)1, fd);
     227                 :             :         
     228                 :           0 :         nbytes = fwrite(data->g, sizeof(cmph_uint32)*data->n, (size_t)1, fd);
     229                 :           0 :         if (nbytes == 0 && ferror(fd)) {
     230                 :           0 :           fprintf(stderr, "ERROR: %s\n", strerror(errno));
     231                 :           0 :           return 0;
     232                 :             :         }
     233                 :             : /*      #ifdef DEBUG
     234                 :             :         fprintf(stderr, "G: ");
     235                 :             :         for (i = 0; i < data->n; ++i) fprintf(stderr, "%u ", data->g[i]);
     236                 :             :         fprintf(stderr, "\n");
     237                 :             :         #endif*/
     238                 :           0 :         return 1;
     239                 :             : }
     240                 :             : 
     241                 :           0 : void chm_load(FILE *f, cmph_t *mphf)
     242                 :             : {
     243                 :             :         cmph_uint32 nhashes;
     244                 :           0 :         char *buf = NULL;
     245                 :             :         cmph_uint32 buflen;
     246                 :             :         cmph_uint32 i;
     247                 :           0 :         chm_data_t *chm = (chm_data_t *)malloc(sizeof(chm_data_t));
     248                 :             :         register size_t nbytes;
     249                 :             :         DEBUGP("Loading chm mphf\n");
     250                 :           0 :         mphf->data = chm;
     251                 :           0 :         nbytes = fread(&nhashes, sizeof(cmph_uint32), (size_t)1, f);
     252                 :           0 :         chm->hashes = (hash_state_t **)malloc(sizeof(hash_state_t *)*(nhashes + 1));
     253                 :           0 :         chm->hashes[nhashes] = NULL;
     254                 :             :         DEBUGP("Reading %u hashes\n", nhashes);
     255                 :           0 :         for (i = 0; i < nhashes; ++i)
     256                 :             :         {
     257                 :           0 :                 hash_state_t *state = NULL;
     258                 :           0 :                 nbytes = fread(&buflen, sizeof(cmph_uint32), (size_t)1, f);
     259                 :             :                 DEBUGP("Hash state has %u bytes\n", buflen);
     260                 :           0 :                 buf = (char *)malloc((size_t)buflen);
     261                 :           0 :                 nbytes = fread(buf, (size_t)buflen, (size_t)1, f);
     262                 :           0 :                 state = hash_state_load(buf, buflen);
     263                 :           0 :                 chm->hashes[i] = state;
     264                 :           0 :                 free(buf);
     265                 :             :         }
     266                 :             : 
     267                 :             :         DEBUGP("Reading m and n\n");
     268                 :           0 :         nbytes = fread(&(chm->n), sizeof(cmph_uint32), (size_t)1, f);    
     269                 :           0 :         nbytes = fread(&(chm->m), sizeof(cmph_uint32), (size_t)1, f);    
     270                 :             : 
     271                 :           0 :         chm->g = (cmph_uint32 *)malloc(sizeof(cmph_uint32)*chm->n);
     272                 :           0 :         nbytes = fread(chm->g, chm->n*sizeof(cmph_uint32), (size_t)1, f);
     273                 :           0 :         if (nbytes == 0 && ferror(f)) {
     274                 :           0 :           fprintf(stderr, "ERROR: %s\n", strerror(errno));
     275                 :           0 :           return;
     276                 :             :         }
     277                 :             :         #ifdef DEBUG
     278                 :             :         fprintf(stderr, "G: ");
     279                 :             :         for (i = 0; i < chm->n; ++i) fprintf(stderr, "%u ", chm->g[i]);
     280                 :             :         fprintf(stderr, "\n");
     281                 :             :         #endif
     282                 :           0 :         return;
     283                 :             : }
     284                 :             :                 
     285                 :             : 
     286                 :           0 : cmph_uint32 chm_search(cmph_t *mphf, const char *key, cmph_uint32 keylen)
     287                 :             : {
     288                 :           0 :         chm_data_t *chm = mphf->data;
     289                 :           0 :         cmph_uint32 h1 = hash(chm->hashes[0], key, keylen) % chm->n;
     290                 :           0 :         cmph_uint32 h2 = hash(chm->hashes[1], key, keylen) % chm->n;
     291                 :             :         DEBUGP("key: %s h1: %u h2: %u\n", key, h1, h2);
     292                 :           0 :         if (h1 == h2 && ++h2 >= chm->n) h2 = 0;
     293                 :             :         DEBUGP("key: %s g[h1]: %u g[h2]: %u edges: %u\n", key, chm->g[h1], chm->g[h2], chm->m);
     294                 :           0 :         return (chm->g[h1] + chm->g[h2]) % chm->m;
     295                 :             : }
     296                 :           0 : void chm_destroy(cmph_t *mphf)
     297                 :             : {
     298                 :           0 :         chm_data_t *data = (chm_data_t *)mphf->data;
     299                 :           0 :         free(data->g);       
     300                 :           0 :         hash_state_destroy(data->hashes[0]);
     301                 :           0 :         hash_state_destroy(data->hashes[1]);
     302                 :           0 :         free(data->hashes);
     303                 :           0 :         free(data);
     304                 :           0 :         free(mphf);
     305                 :           0 : }
     306                 :             : 
     307                 :             : /** \fn void chm_pack(cmph_t *mphf, void *packed_mphf);
     308                 :             :  *  \brief Support the ability to pack a perfect hash function into a preallocated contiguous memory space pointed by packed_mphf.
     309                 :             :  *  \param mphf pointer to the resulting mphf
     310                 :             :  *  \param packed_mphf pointer to the contiguous memory area used to store the resulting mphf. The size of packed_mphf must be at least cmph_packed_size() 
     311                 :             :  */
     312                 :           0 : void chm_pack(cmph_t *mphf, void *packed_mphf)
     313                 :             : {
     314                 :           0 :         chm_data_t *data = (chm_data_t *)mphf->data;
     315                 :           0 :         cmph_uint8 * ptr = packed_mphf;
     316                 :             :         CMPH_HASH h2_type;
     317                 :             : 
     318                 :             :         // packing h1 type
     319                 :           0 :         CMPH_HASH h1_type = hash_get_type(data->hashes[0]);
     320                 :           0 :         *((cmph_uint32 *) ptr) = h1_type;
     321                 :           0 :         ptr += sizeof(cmph_uint32);
     322                 :             : 
     323                 :             :         // packing h1
     324                 :           0 :         hash_state_pack(data->hashes[0], ptr);
     325                 :           0 :         ptr += hash_state_packed_size(h1_type);
     326                 :             : 
     327                 :             :         // packing h2 type
     328                 :           0 :         h2_type = hash_get_type(data->hashes[1]);
     329                 :           0 :         *((cmph_uint32 *) ptr) = h2_type;
     330                 :           0 :         ptr += sizeof(cmph_uint32);
     331                 :             : 
     332                 :             :         // packing h2
     333                 :           0 :         hash_state_pack(data->hashes[1], ptr);
     334                 :           0 :         ptr += hash_state_packed_size(h2_type);
     335                 :             : 
     336                 :             :         // packing n
     337                 :           0 :         *((cmph_uint32 *) ptr) = data->n;
     338                 :           0 :         ptr += sizeof(data->n);
     339                 :             : 
     340                 :             :         // packing m
     341                 :           0 :         *((cmph_uint32 *) ptr) = data->m;
     342                 :           0 :         ptr += sizeof(data->m);
     343                 :             : 
     344                 :             :         // packing g
     345                 :           0 :         memcpy(ptr, data->g, sizeof(cmph_uint32)*data->n);        
     346                 :           0 : }
     347                 :             : 
     348                 :             : /** \fn cmph_uint32 chm_packed_size(cmph_t *mphf);
     349                 :             :  *  \brief Return the amount of space needed to pack mphf.
     350                 :             :  *  \param mphf pointer to a mphf
     351                 :             :  *  \return the size of the packed function or zero for failures
     352                 :             :  */ 
     353                 :           0 : cmph_uint32 chm_packed_size(cmph_t *mphf)
     354                 :             : {
     355                 :           0 :         chm_data_t *data = (chm_data_t *)mphf->data;
     356                 :           0 :         CMPH_HASH h1_type = hash_get_type(data->hashes[0]); 
     357                 :           0 :         CMPH_HASH h2_type = hash_get_type(data->hashes[1]); 
     358                 :             : 
     359                 :           0 :         return (cmph_uint32)(sizeof(CMPH_ALGO) + hash_state_packed_size(h1_type) + hash_state_packed_size(h2_type) + 
     360                 :           0 :                         4*sizeof(cmph_uint32) + sizeof(cmph_uint32)*data->n);
     361                 :             : }
     362                 :             : 
     363                 :             : /** cmph_uint32 chm_search(void *packed_mphf, const char *key, cmph_uint32 keylen);
     364                 :             :  *  \brief Use the packed mphf to do a search. 
     365                 :             :  *  \param  packed_mphf pointer to the packed mphf
     366                 :             :  *  \param key key to be hashed
     367                 :             :  *  \param keylen key length in bytes
     368                 :             :  *  \return The mphf value
     369                 :             :  */
     370                 :           0 : cmph_uint32 chm_search_packed(void *packed_mphf, const char *key, cmph_uint32 keylen)
     371                 :             : {
     372                 :           0 :         register cmph_uint8 *h1_ptr = packed_mphf;
     373                 :           0 :         register CMPH_HASH h1_type  = *((cmph_uint32 *)h1_ptr);
     374                 :             :         register cmph_uint8 *h2_ptr;
     375                 :             :         register CMPH_HASH h2_type;
     376                 :             :         register cmph_uint32 *g_ptr;
     377                 :             :         register cmph_uint32 n, m, h1, h2;
     378                 :             : 
     379                 :           0 :         h1_ptr += 4;
     380                 :             : 
     381                 :           0 :         h2_ptr = h1_ptr + hash_state_packed_size(h1_type);
     382                 :           0 :         h2_type  = *((cmph_uint32 *)h2_ptr);
     383                 :           0 :         h2_ptr += 4;
     384                 :             :         
     385                 :           0 :         g_ptr = (cmph_uint32 *)(h2_ptr + hash_state_packed_size(h2_type));
     386                 :             :         
     387                 :           0 :         n = *g_ptr++;
     388                 :           0 :         m = *g_ptr++;
     389                 :             :         
     390                 :           0 :         h1 = hash_packed(h1_ptr, h1_type, key, keylen) % n;
     391                 :           0 :         h2 = hash_packed(h2_ptr, h2_type, key, keylen) % n;
     392                 :             :         DEBUGP("key: %s h1: %u h2: %u\n", key, h1, h2);
     393                 :           0 :         if (h1 == h2 && ++h2 >= n) h2 = 0;
     394                 :             :         DEBUGP("key: %s g[h1]: %u g[h2]: %u edges: %u\n", key, g_ptr[h1], g_ptr[h2], m);
     395                 :           0 :         return (g_ptr[h1] + g_ptr[h2]) % m;     
     396                 :             : }
        

Generated by: LCOV version 2.0-1