i#7690: hashtable_t key-exposing iterator (#7691)

Adds a new iterator `hashtable_apply_to_all_key_payload_pairs_user_data()`
over DynamoRIO's container `hashtable_t` that exposes the key and payload
pair of every element.

Adds a test for the new iterator using count and sum of hashtable elements.

Adds the new iterator to release doc.

Fixes #7690

Author: edeiana

api/docs/release.dox

@@ -269,6 +269,8 @@ Further non-compatibility-affecting changes include:
    PC in the trace, which is from the next instruction or the next
    #dynamorio::drmemtrace::TRACE_MARKER_TYPE_KERNEL_EVENT marker, whichever comes
    first.
+ - Added a new #hashtable_t iterator hashtable_apply_to_all_key_payload_pairs_user_data()
+   that exposes the key of every element in the table.
 
 **************************************************
 <hr>

ext/drcontainers/hashtable.c

@@ -504,6 +504,19 @@ hashtable_apply_to_all_payloads_user_data(hashtable_t *table,
     }
 }
 
+void
+hashtable_apply_to_all_key_payload_pairs_user_data(
+    hashtable_t *table, void (*apply_func)(void *key, void *payload, void *user_data),
+    void *user_data)
+{
+    DR_ASSERT_MSG(apply_func != NULL, "The apply_func ptr cannot be NULL.");
+    for (uint i = 0; i < HASHTABLE_SIZE(table->table_bits); i++) {
+        for (hash_entry_t *e = table->table[i]; e != NULL; e = e->next) {
+            apply_func(e->key, e->payload, user_data);
+        }
+    }
+}
+
 static void
 hashtable_clear_internal(hashtable_t *table)
 {

ext/drcontainers/hashtable.h

@@ -87,6 +87,7 @@ typedef struct _hashtable_config_t {
     void (*free_key_func)(void *);
 } hashtable_config_t;
 
+/** The storage for a hashtable. */
 typedef struct _hashtable_t {
     hash_entry_t **table;
     hash_type_t hashtype;
@@ -205,17 +206,19 @@ hashtable_remove_range(hashtable_t *table, void *start, void *end);
  * Calls the \p apply_func for each payload.
  * @param table The hashtable to apply the function.
  * @param apply_func A pointer to a function that is called for all payloads
- * stored in the map.
+ * stored in the map. The function is not allowed to add or remove elements to/from the
+ * hashtable being iterated.
  */
 void
 hashtable_apply_to_all_payloads(hashtable_t *table, void (*apply_func)(void *payload));
 
 /**
- * Calls the \p apply_func for each payload with user data. Similar to
- * hashtable_apply_to_all_payloads().
+ * Calls the \p apply_func for each payload with user data.
+ * Similar to hashtable_apply_to_all_payloads().
  * @param table The hashtable to apply the function.
  * @param apply_func A pointer to a function that is called for all payloads
- * stored in the map. It also takes user data as a parameter.
+ * stored in the map. It also takes user data as a parameter. The function is not allowed
+ * to add or remove elements to/from the hashtable being iterated.
  * @param user_data User data that is available when iterating through payloads.
  */
 void
@@ -224,6 +227,20 @@ hashtable_apply_to_all_payloads_user_data(hashtable_t *table,
                                                              void *user_data),
                                           void *user_data);
 
+/**
+ * Calls the \p apply_func for each key-payload pair with user data.
+ * Similar to hashtable_apply_to_all_payloads_user_data().
+ * @param table The hashtable to apply the function.
+ * @param apply_func A pointer to a function that is called for all key-payload pairs
+ * stored in the map. It also takes user data as a parameter. The function is not allowed
+ * to add or remove elements to/from the hashtable being iterated.
+ * @param user_data User data that is available when iterating through payloads.
+ */
+void
+hashtable_apply_to_all_key_payload_pairs_user_data(
+    hashtable_t *table, void (*apply_func)(void *key, void *payload, void *user_data),
+    void *user_data);
+
 /**
  * Removes all entries from the table.  If free_payload_func was specified
  * calls it for each payload.

suite/tests/client-interface/drcontainers-test.dll.c

@@ -38,6 +38,11 @@
 #include "hashtable.h"
 #include "stdint.h"
 
+typedef struct _accumulators_t {
+    uintptr_t key_acc;
+    uintptr_t payload_acc;
+} accumulators_t;
+
 static void
 test_vector(void)
 {
@@ -105,6 +110,16 @@ count_user_data(void *payload, void *user_data)
     CHECK(user_data == (void *)apply_payload_user_data_test, "user data not correct");
 }
 
+static void
+count_key_payload_user_data(void *key, void *payload, void *user_data)
+{
+    accumulators_t *counters = (accumulators_t *)user_data;
+    /* Count key. */
+    ++counters->key_acc;
+    /* Count payload. */
+    ++counters->payload_acc;
+}
+
 static void
 count_null_user_data(void *payload, void *user_data)
 {
@@ -125,6 +140,14 @@ sum_user_data(void *payload, void *user_data)
     total += (uintptr_t)user_data;
 }
 
+static void
+sum_key_payload_user_data(void *key, void *payload, void *user_data)
+{
+    accumulators_t *sums = (accumulators_t *)user_data;
+    sums->key_acc += (uintptr_t)key;
+    sums->payload_acc += (uintptr_t)payload;
+}
+
 static void
 test_hashtable_apply_all(void)
 {
@@ -182,6 +205,32 @@ test_hashtable_apply_all_user_data(void)
     hashtable_delete(&hash_table);
 }
 
+static void
+test_hashtable_apply_all_key_payload_pairs_user_data(void)
+{
+    hashtable_t hash_table;
+    hashtable_init(&hash_table, 8, HASH_INTPTR, false);
+
+    hashtable_add_replace(&hash_table, (void *)1, (void *)1);
+    hashtable_add_replace(&hash_table, (void *)2, (void *)2);
+    hashtable_add_replace(&hash_table, (void *)3, (void *)3);
+
+    accumulators_t counters = { .key_acc = 0, .payload_acc = 0 };
+    hashtable_apply_to_all_key_payload_pairs_user_data(
+        &hash_table, count_key_payload_user_data, (void *)&counters);
+    accumulators_t sums = { .key_acc = 0, .payload_acc = 0 };
+    hashtable_apply_to_all_key_payload_pairs_user_data(
+        &hash_table, sum_key_payload_user_data, (void *)&sums);
+
+    CHECK((counters.key_acc == (uintptr_t)hash_table.entries) &&
+              (counters.payload_acc == (uintptr_t)hash_table.entries),
+          "hashtable_apply_to_all_key_payload_pairs_user_data (count test) failed");
+    CHECK((sums.key_acc == 6) && (sums.payload_acc == 6),
+          "hashtable_apply_to_all_key_payload_pairs_user_data (sum test) failed");
+
+    hashtable_delete(&hash_table);
+}
+
 #define KEY 42
 #define PAYLOAD ((void *)12)
 static bool free_func_called;
@@ -217,6 +266,7 @@ dr_init(client_id_t id)
     test_vector();
     test_hashtable_apply_all();
     test_hashtable_apply_all_user_data();
+    test_hashtable_apply_all_key_payload_pairs_user_data();
     test_dr_hashtable();
 
     /* XXX: test other data structures */