diff options
author | Christian Grothoff <christian@grothoff.org> | 2017-01-17 16:40:19 +0100 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2017-01-17 16:40:19 +0100 |
commit | 5d52f126f510a223d371459f17d5aaa46e9dfe49 (patch) | |
tree | c9776ec0110b8874a7f0d4c2ea96a98750c61449 /src/include/gnunet_container_lib.h | |
parent | c87a389a4f842c20383d8619120b188e104cf64a (diff) | |
download | gnunet-5d52f126f510a223d371459f17d5aaa46e9dfe49.tar.gz gnunet-5d52f126f510a223d371459f17d5aaa46e9dfe49.zip |
introducing the short map
Diffstat (limited to 'src/include/gnunet_container_lib.h')
-rw-r--r-- | src/include/gnunet_container_lib.h | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h index 075c0822a..c99b911a1 100644 --- a/src/include/gnunet_container_lib.h +++ b/src/include/gnunet_container_lib.h | |||
@@ -1285,6 +1285,275 @@ GNUNET_CONTAINER_multipeermap_get_random (const struct GNUNET_CONTAINER_MultiPee | |||
1285 | void *it_cls); | 1285 | void *it_cls); |
1286 | 1286 | ||
1287 | 1287 | ||
1288 | /* ***************** Version of Multihashmap for short hashes ****************** */ | ||
1289 | |||
1290 | /** | ||
1291 | * @ingroup hashmap | ||
1292 | * Iterator over hash map entries. | ||
1293 | * | ||
1294 | * @param cls closure | ||
1295 | * @param key current public key | ||
1296 | * @param value value in the hash map | ||
1297 | * @return #GNUNET_YES if we should continue to | ||
1298 | * iterate, | ||
1299 | * #GNUNET_NO if not. | ||
1300 | */ | ||
1301 | typedef int | ||
1302 | (*GNUNET_CONTAINER_ShortmapIterator) (void *cls, | ||
1303 | const struct GNUNET_PeerIdentity *key, | ||
1304 | void *value); | ||
1305 | |||
1306 | |||
1307 | /** | ||
1308 | * Hash map from peer identities to values. | ||
1309 | */ | ||
1310 | struct GNUNET_CONTAINER_MultiShortmap; | ||
1311 | |||
1312 | |||
1313 | /** | ||
1314 | * @ingroup hashmap | ||
1315 | * Create a multi peer map (hash map for public keys of peers). | ||
1316 | * | ||
1317 | * @param len initial size (map will grow as needed) | ||
1318 | * @param do_not_copy_keys #GNUNET_NO is always safe and should be used by default; | ||
1319 | * #GNUNET_YES means that on 'put', the 'key' does not have | ||
1320 | * to be copied as the destination of the pointer is | ||
1321 | * guaranteed to be life as long as the value is stored in | ||
1322 | * the hashmap. This can significantly reduce memory | ||
1323 | * consumption, but of course is also a recipie for | ||
1324 | * heap corruption if the assumption is not true. Only | ||
1325 | * use this if (1) memory use is important in this case and | ||
1326 | * (2) you have triple-checked that the invariant holds | ||
1327 | * @return NULL on error | ||
1328 | */ | ||
1329 | struct GNUNET_CONTAINER_MultiShortmap * | ||
1330 | GNUNET_CONTAINER_multishortmap_create (unsigned int len, | ||
1331 | int do_not_copy_keys); | ||
1332 | |||
1333 | |||
1334 | /** | ||
1335 | * @ingroup hashmap | ||
1336 | * Destroy a hash map. Will not free any values | ||
1337 | * stored in the hash map! | ||
1338 | * | ||
1339 | * @param map the map | ||
1340 | */ | ||
1341 | void | ||
1342 | GNUNET_CONTAINER_multishortmap_destroy (struct GNUNET_CONTAINER_MultiShortmap *map); | ||
1343 | |||
1344 | |||
1345 | /** | ||
1346 | * @ingroup hashmap | ||
1347 | * Given a key find a value in the map matching the key. | ||
1348 | * | ||
1349 | * @param map the map | ||
1350 | * @param key what to look for | ||
1351 | * @return NULL if no value was found; note that | ||
1352 | * this is indistinguishable from values that just | ||
1353 | * happen to be NULL; use "contains" to test for | ||
1354 | * key-value pairs with value NULL | ||
1355 | */ | ||
1356 | void * | ||
1357 | GNUNET_CONTAINER_multishortmap_get (const struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1358 | const struct GNUNET_PeerIdentity *key); | ||
1359 | |||
1360 | |||
1361 | /** | ||
1362 | * @ingroup hashmap | ||
1363 | * Remove the given key-value pair from the map. Note that if the | ||
1364 | * key-value pair is in the map multiple times, only one of the pairs | ||
1365 | * will be removed. | ||
1366 | * | ||
1367 | * @param map the map | ||
1368 | * @param key key of the key-value pair | ||
1369 | * @param value value of the key-value pair | ||
1370 | * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair | ||
1371 | * is not in the map | ||
1372 | */ | ||
1373 | int | ||
1374 | GNUNET_CONTAINER_multishortmap_remove (struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1375 | const struct GNUNET_PeerIdentity * key, | ||
1376 | const void *value); | ||
1377 | |||
1378 | /** | ||
1379 | * @ingroup hashmap | ||
1380 | * Remove all entries for the given key from the map. | ||
1381 | * Note that the values would not be "freed". | ||
1382 | * | ||
1383 | * @param map the map | ||
1384 | * @param key identifies values to be removed | ||
1385 | * @return number of values removed | ||
1386 | */ | ||
1387 | int | ||
1388 | GNUNET_CONTAINER_multishortmap_remove_all (struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1389 | const struct GNUNET_PeerIdentity *key); | ||
1390 | |||
1391 | |||
1392 | /** | ||
1393 | * @ingroup hashmap | ||
1394 | * Check if the map contains any value under the given | ||
1395 | * key (including values that are NULL). | ||
1396 | * | ||
1397 | * @param map the map | ||
1398 | * @param key the key to test if a value exists for it | ||
1399 | * @return #GNUNET_YES if such a value exists, | ||
1400 | * #GNUNET_NO if not | ||
1401 | */ | ||
1402 | int | ||
1403 | GNUNET_CONTAINER_multishortmap_contains (const struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1404 | const struct GNUNET_PeerIdentity *key); | ||
1405 | |||
1406 | |||
1407 | /** | ||
1408 | * @ingroup hashmap | ||
1409 | * Check if the map contains the given value under the given | ||
1410 | * key. | ||
1411 | * | ||
1412 | * @param map the map | ||
1413 | * @param key the key to test if a value exists for it | ||
1414 | * @param value value to test for | ||
1415 | * @return #GNUNET_YES if such a value exists, | ||
1416 | * #GNUNET_NO if not | ||
1417 | */ | ||
1418 | int | ||
1419 | GNUNET_CONTAINER_multishortmap_contains_value (const struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1420 | const struct GNUNET_PeerIdentity * key, | ||
1421 | const void *value); | ||
1422 | |||
1423 | |||
1424 | /** | ||
1425 | * @ingroup hashmap | ||
1426 | * Store a key-value pair in the map. | ||
1427 | * | ||
1428 | * @param map the map | ||
1429 | * @param key key to use | ||
1430 | * @param value value to use | ||
1431 | * @param opt options for put | ||
1432 | * @return #GNUNET_OK on success, | ||
1433 | * #GNUNET_NO if a value was replaced (with REPLACE) | ||
1434 | * #GNUNET_SYSERR if #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY was the option and the | ||
1435 | * value already exists | ||
1436 | */ | ||
1437 | int | ||
1438 | GNUNET_CONTAINER_multishortmap_put (struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1439 | const struct GNUNET_PeerIdentity *key, | ||
1440 | void *value, | ||
1441 | enum GNUNET_CONTAINER_MultiHashMapOption opt); | ||
1442 | |||
1443 | |||
1444 | /** | ||
1445 | * @ingroup hashmap | ||
1446 | * Get the number of key-value pairs in the map. | ||
1447 | * | ||
1448 | * @param map the map | ||
1449 | * @return the number of key value pairs | ||
1450 | */ | ||
1451 | unsigned int | ||
1452 | GNUNET_CONTAINER_multishortmap_size (const struct GNUNET_CONTAINER_MultiShortmap *map); | ||
1453 | |||
1454 | |||
1455 | /** | ||
1456 | * @ingroup hashmap | ||
1457 | * Iterate over all entries in the map. | ||
1458 | * | ||
1459 | * @param map the map | ||
1460 | * @param it function to call on each entry | ||
1461 | * @param it_cls extra argument to @a it | ||
1462 | * @return the number of key value pairs processed, | ||
1463 | * #GNUNET_SYSERR if it aborted iteration | ||
1464 | */ | ||
1465 | int | ||
1466 | GNUNET_CONTAINER_multishortmap_iterate (const struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1467 | GNUNET_CONTAINER_ShortmapIterator it, | ||
1468 | void *it_cls); | ||
1469 | |||
1470 | |||
1471 | struct GNUNET_CONTAINER_MultiShortmapIterator; | ||
1472 | |||
1473 | |||
1474 | /** | ||
1475 | * @ingroup hashmap | ||
1476 | * Create an iterator for a multihashmap. | ||
1477 | * The iterator can be used to retrieve all the elements in the multihashmap | ||
1478 | * one by one, without having to handle all elements at once (in contrast to | ||
1479 | * #GNUNET_CONTAINER_multishortmap_iterate). Note that the iterator can not be | ||
1480 | * used anymore if elements have been removed from @a map after the creation of | ||
1481 | * the iterator, or 'map' has been destroyed. Adding elements to @a map may | ||
1482 | * result in skipped or repeated elements. | ||
1483 | * | ||
1484 | * @param map the map to create an iterator for | ||
1485 | * @return an iterator over the given multihashmap @a map | ||
1486 | */ | ||
1487 | struct GNUNET_CONTAINER_MultiShortmapIterator * | ||
1488 | GNUNET_CONTAINER_multishortmap_iterator_create (const struct GNUNET_CONTAINER_MultiShortmap *map); | ||
1489 | |||
1490 | |||
1491 | /** | ||
1492 | * @ingroup hashmap | ||
1493 | * Retrieve the next element from the hash map at the iterator's | ||
1494 | * position. If there are no elements left, #GNUNET_NO is returned, | ||
1495 | * and @a key and @a value are not modified. This operation is only | ||
1496 | * allowed if no elements have been removed from the multihashmap | ||
1497 | * since the creation of @a iter, and the map has not been destroyed. | ||
1498 | * Adding elements may result in repeating or skipping elements. | ||
1499 | * | ||
1500 | * @param iter the iterator to get the next element from | ||
1501 | * @param key pointer to store the key in, can be NULL | ||
1502 | * @param value pointer to store the value in, can be NULL | ||
1503 | * @return #GNUNET_YES we returned an element, | ||
1504 | * #GNUNET_NO if we are out of elements | ||
1505 | */ | ||
1506 | int | ||
1507 | GNUNET_CONTAINER_multishortmap_iterator_next (struct GNUNET_CONTAINER_MultiShortmapIterator *iter, | ||
1508 | struct GNUNET_PeerIdentity *key, | ||
1509 | const void **value); | ||
1510 | |||
1511 | |||
1512 | /** | ||
1513 | * @ingroup hashmap | ||
1514 | * Destroy a multishortmap iterator. | ||
1515 | * | ||
1516 | * @param iter the iterator to destroy | ||
1517 | */ | ||
1518 | void | ||
1519 | GNUNET_CONTAINER_multishortmap_iterator_destroy (struct GNUNET_CONTAINER_MultiShortmapIterator *iter); | ||
1520 | |||
1521 | |||
1522 | /** | ||
1523 | * @ingroup hashmap | ||
1524 | * Iterate over all entries in the map that match a particular key. | ||
1525 | * | ||
1526 | * @param map the map | ||
1527 | * @param key public key that the entries must correspond to | ||
1528 | * @param it function to call on each entry | ||
1529 | * @param it_cls extra argument to @a it | ||
1530 | * @return the number of key value pairs processed, | ||
1531 | * #GNUNET_SYSERR if it aborted iteration | ||
1532 | */ | ||
1533 | int | ||
1534 | GNUNET_CONTAINER_multishortmap_get_multiple (const struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1535 | const struct GNUNET_PeerIdentity *key, | ||
1536 | GNUNET_CONTAINER_ShortmapIterator it, | ||
1537 | void *it_cls); | ||
1538 | |||
1539 | |||
1540 | /** | ||
1541 | * @ingroup hashmap | ||
1542 | * Call @a it on a random value from the map, or not at all | ||
1543 | * if the map is empty. Note that this function has linear | ||
1544 | * complexity (in the size of the map). | ||
1545 | * | ||
1546 | * @param map the map | ||
1547 | * @param it function to call on a random entry | ||
1548 | * @param it_cls extra argument to @a it | ||
1549 | * @return the number of key value pairs processed, zero or one. | ||
1550 | */ | ||
1551 | unsigned int | ||
1552 | GNUNET_CONTAINER_multishortmap_get_random (const struct GNUNET_CONTAINER_MultiShortmap *map, | ||
1553 | GNUNET_CONTAINER_ShortmapIterator it, | ||
1554 | void *it_cls); | ||
1555 | |||
1556 | |||
1288 | /* Version of multihashmap with 32 bit keys */ | 1557 | /* Version of multihashmap with 32 bit keys */ |
1289 | 1558 | ||
1290 | /** | 1559 | /** |