+/**
+ * @ingroup hashmap
+ * Call @a it on a random value from the map, or not at all
+ * if the map is empty. Note that this function has linear
+ * complexity (in the size of the map).
+ *
+ * @param map the map
+ * @param it function to call on a random entry
+ * @param it_cls extra argument to @a it
+ * @return the number of key value pairs processed, zero or one.
+ */
+unsigned int
+GNUNET_CONTAINER_multihashmap_get_random (const struct GNUNET_CONTAINER_MultiHashMap *map,
+ GNUNET_CONTAINER_HashMapIterator it,
+ void *it_cls)
+{
+ unsigned int off;
+ unsigned int idx;
+ union MapEntry me;
+
+ if (0 == map->size)
+ return 0;
+ if (NULL == it)
+ return 1;
+ off = GNUNET_CRYPTO_random_u32 (GNUNET_CRYPTO_QUALITY_NONCE,
+ map->size);
+ for (idx = 0; idx < map->map_length; idx++)
+ {
+ me = map->map[idx];
+ if (map->use_small_entries)
+ {
+ struct SmallMapEntry *sme;
+ struct SmallMapEntry *nxt;
+
+ nxt = me.sme;
+ while (NULL != (sme = nxt))
+ {
+ nxt = sme->next;
+ if (0 == off)
+ {
+ if (GNUNET_OK != it (it_cls,
+ sme->key,
+ sme->value))
+ return GNUNET_SYSERR;
+ return 1;
+ }
+ off--;
+ }
+ }
+ else
+ {
+ struct BigMapEntry *bme;
+ struct BigMapEntry *nxt;
+
+ nxt = me.bme;
+ while (NULL != (bme = nxt))
+ {
+ nxt = bme->next;
+ if (0 == off)
+ {
+ if (GNUNET_OK != it (it_cls,
+ &bme->key, bme->value))
+ return GNUNET_SYSERR;
+ return 1;
+ }
+ off--;
+ }
+ }
+ }
+ GNUNET_break (0);
+ return GNUNET_SYSERR;
+}
+
+
+/**
+ * Create an iterator for a multihashmap.
+ * The iterator can be used to retrieve all the elements in the multihashmap
+ * one by one, without having to handle all elements at once (in contrast to
+ * GNUNET_CONTAINER_multihashmap_iterate()). Note that the iterator can not be
+ * used anymore if elements have been removed from 'map' after the creation of
+ * the iterator, or 'map' has been destroyed. Adding elements to 'map' may
+ * result in skipped or repeated elements.
+ *
+ * @param map the map to create an iterator for
+ * @return an iterator over the given multihashmap 'map'
+ */
+struct GNUNET_CONTAINER_MultiHashMapIterator *
+GNUNET_CONTAINER_multihashmap_iterator_create (const struct GNUNET_CONTAINER_MultiHashMap *map)
+{
+ struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
+
+ iter = GNUNET_new (struct GNUNET_CONTAINER_MultiHashMapIterator);
+ iter->map = map;
+ iter->modification_counter = map->modification_counter;
+ iter->me = map->map[0];
+ return iter;
+}
+
+
+/**
+ * Retrieve the next element from the hash map at the iterator's position.
+ * If there are no elements left, GNUNET_NO is returned, and 'key' and 'value'
+ * are not modified.
+ * This operation is only allowed if no elements have been removed from the
+ * multihashmap since the creation of 'iter', and the map has not been destroyed.
+ * Adding elements may result in repeating or skipping elements.
+ *
+ * @param iter the iterator to get the next element from
+ * @param key pointer to store the key in, can be NULL
+ * @param value pointer to store the value in, can be NULL
+ * @return #GNUNET_YES we returned an element,
+ * #GNUNET_NO if we are out of elements
+ */
+int
+GNUNET_CONTAINER_multihashmap_iterator_next (struct GNUNET_CONTAINER_MultiHashMapIterator *iter,
+ struct GNUNET_HashCode *key,
+ const void **value)
+{
+ /* make sure the map has not been modified */
+ GNUNET_assert (iter->modification_counter == iter->map->modification_counter);
+
+ /* look for the next entry, skipping empty buckets */
+ while (1)
+ {
+ if (iter->idx >= iter->map->map_length)
+ return GNUNET_NO;
+ if (GNUNET_YES == iter->map->use_small_entries)
+ {
+ if (NULL != iter->me.sme)
+ {
+ if (NULL != key)
+ *key = *iter->me.sme->key;
+ if (NULL != value)
+ *value = iter->me.sme->value;
+ iter->me.sme = iter->me.sme->next;
+ return GNUNET_YES;
+ }
+ }
+ else
+ {
+ if (NULL != iter->me.bme)
+ {
+ if (NULL != key)
+ *key = iter->me.bme->key;
+ if (NULL != value)
+ *value = iter->me.bme->value;
+ iter->me.bme = iter->me.bme->next;
+ return GNUNET_YES;
+ }
+ }
+ iter->idx += 1;
+ if (iter->idx < iter->map->map_length)
+ iter->me = iter->map->map[iter->idx];
+ }
+}
+
+
+/**
+ * Destroy a multihashmap iterator.
+ *
+ * @param iter the iterator to destroy
+ */
+void
+GNUNET_CONTAINER_multihashmap_iterator_destroy (struct GNUNET_CONTAINER_MultiHashMapIterator *iter)
+{
+ GNUNET_free (iter);
+}
+
+