tolerate additional IPv4 address now available for gnunet.org
[oweals/gnunet.git] / src / util / container_multipeermap.c
index 8ec3a2077e2c3efd539b6c26fa82fe8cce57eeb8..613efc0a9d4f67eb066b1ab372c9c2fd7c546556 100644 (file)
@@ -1,21 +1,21 @@
 /*
      This file is part of GNUnet.
-     (C) 2008, 2012 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2008, 2012 GNUnet e.V.
 
-     GNUnet is free software; you can redistribute it and/or modify
-     it under the terms of the GNU General Public License as published
-     by the Free Software Foundation; either version 3, or (at your
-     option) any later version.
+     GNUnet is free software: you can redistribute it and/or modify it
+     under the terms of the GNU Affero General Public License as published
+     by the Free Software Foundation, either version 3 of the License,
+     or (at your option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-     General Public License for more details.
+     Affero General Public License for more details.
 
-     You should have received a copy of the GNU General Public License
-     along with GNUnet; see the file COPYING.  If not, write to the
-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     You should have received a copy of the GNU Affero General Public License
+     along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+     SPDX-License-Identifier: AGPL3.0-or-later
 */
 /**
  * @file util/container_multipeermap.c
 #include "platform.h"
 #include "gnunet_util_lib.h"
 
-#define LOG(kind,...) GNUNET_log_from (kind, "util", __VA_ARGS__)
+#define LOG(kind,...) GNUNET_log_from (kind, "util-container-multipeermap", __VA_ARGS__)
+
+/**
+ * Maximum recursion depth for callbacks of
+ * #GNUNET_CONTAINER_multihashmap_get_multiple() themselve s
+ * again calling #GNUNET_CONTAINER_multihashmap_get_multiple().
+ * Should be totally excessive, but if violated we die.
+ */
+#define NEXT_CACHE_SIZE 16
 
 /**
  * An entry in the hash map with the full key.
@@ -114,8 +122,8 @@ struct GNUNET_CONTAINER_MultiPeerMap
   unsigned int map_length;
 
   /**
-   * GNUNET_NO if the map entries are of type 'struct BigMapEntry',
-   * GNUNET_YES if the map entries are of type 'struct SmallMapEntry'.
+   * #GNUNET_NO if the map entries are of type 'struct BigMapEntry',
+   * #GNUNET_YES if the map entries are of type 'struct SmallMapEntry'.
    */
   int use_small_entries;
 
@@ -124,6 +132,19 @@ struct GNUNET_CONTAINER_MultiPeerMap
    * to the map, so that iterators can check if they are still valid.
    */
   unsigned int modification_counter;
+
+  /**
+   * Map entries indicating iteration positions currently
+   * in use by #GNUNET_CONTAINER_multihashmap_get_multiple().
+   * Only used up to @e next_cache_off.
+   */
+  union MapEntry next_cache[NEXT_CACHE_SIZE];
+
+  /**
+   * Offset of @e next_cache entries in use, must be smaller
+   * than #NEXT_CACHE_SIZE.
+   */
+  unsigned int next_cache_off;
 };
 
 
@@ -179,7 +200,13 @@ GNUNET_CONTAINER_multipeermap_create (unsigned int len,
 
   GNUNET_assert (len > 0);
   map = GNUNET_new (struct GNUNET_CONTAINER_MultiPeerMap);
-  map->map = GNUNET_malloc (len * sizeof (union MapEntry));
+  map->map = GNUNET_malloc_large (len *
+                                  sizeof (union MapEntry));
+  if (NULL == map->map)
+  {
+    GNUNET_free (map);
+    return NULL;
+  }
   map->map_length = len;
   map->use_small_entries = do_not_copy_keys;
   return map;
@@ -193,14 +220,13 @@ GNUNET_CONTAINER_multipeermap_create (unsigned int len,
  * @param map the map
  */
 void
-GNUNET_CONTAINER_multipeermap_destroy (struct GNUNET_CONTAINER_MultiPeerMap
-                                       *map)
+GNUNET_CONTAINER_multipeermap_destroy (struct GNUNET_CONTAINER_MultiPeerMap *map)
 {
-  unsigned int i;
-  union MapEntry me;
-
-  for (i = 0; i < map->map_length; i++)
+  GNUNET_assert (0 == map->next_cache_off);
+  for (unsigned int i = 0; i < map->map_length; i++)
   {
+    union MapEntry me;
+
     me = map->map[i];
     if (map->use_small_entries)
     {
@@ -245,8 +271,13 @@ static unsigned int
 idx_of (const struct GNUNET_CONTAINER_MultiPeerMap *map,
         const struct GNUNET_PeerIdentity *key)
 {
-  GNUNET_assert (map != NULL);
-  return (*(unsigned int *) key) % map->map_length;
+  unsigned int kx;
+
+  GNUNET_assert (NULL != map);
+  GNUNET_memcpy (&kx,
+                key,
+                sizeof (kx));
+  return kx % map->map_length;
 }
 
 
@@ -257,8 +288,7 @@ idx_of (const struct GNUNET_CONTAINER_MultiPeerMap *map,
  * @return the number of key value pairs
  */
 unsigned int
-GNUNET_CONTAINER_multipeermap_size (const struct GNUNET_CONTAINER_MultiPeerMap
-                                    *map)
+GNUNET_CONTAINER_multipeermap_size (const struct GNUNET_CONTAINER_MultiPeerMap *map)
 {
   return map->size;
 }
@@ -275,26 +305,26 @@ GNUNET_CONTAINER_multipeermap_size (const struct GNUNET_CONTAINER_MultiPeerMap
  *   key-value pairs with value NULL
  */
 void *
-GNUNET_CONTAINER_multipeermap_get (const struct GNUNET_CONTAINER_MultiPeerMap
-                                   *map, const struct GNUNET_PeerIdentity *key)
+GNUNET_CONTAINER_multipeermap_get (const struct GNUNET_CONTAINER_MultiPeerMap *map,
+                                  const struct GNUNET_PeerIdentity *key)
 {
   union MapEntry me;
 
   me = map->map[idx_of (map, key)];
   if (map->use_small_entries)
   {
-    struct SmallMapEntry *sme;
-
-    for (sme = me.sme; NULL != sme; sme = sme->next)
-      if (0 == memcmp (key, sme->key, sizeof (struct GNUNET_PeerIdentity)))
+    for (struct SmallMapEntry *sme = me.sme; NULL != sme; sme = sme->next)
+      if (0 == memcmp (key,
+                      sme->key,
+                      sizeof (struct GNUNET_PeerIdentity)))
        return sme->value;
   }
   else
   {
-    struct BigMapEntry *bme;
-
-    for (bme = me.bme; NULL != bme; bme = bme->next)
-      if (0 == memcmp (key, &bme->key, sizeof (struct GNUNET_PeerIdentity)))
+    for (struct BigMapEntry *bme = me.bme; NULL != bme; bme = bme->next)
+      if (0 == memcmp (key,
+                      &bme->key,
+                      sizeof (struct GNUNET_PeerIdentity)))
        return bme->value;
   }
   return NULL;
@@ -311,34 +341,39 @@ GNUNET_CONTAINER_multipeermap_get (const struct GNUNET_CONTAINER_MultiPeerMap
  *         #GNUNET_SYSERR if it aborted iteration
  */
 int
-GNUNET_CONTAINER_multipeermap_iterate (const struct
-                                       GNUNET_CONTAINER_MultiPeerMap *map,
+GNUNET_CONTAINER_multipeermap_iterate (struct GNUNET_CONTAINER_MultiPeerMap *map,
                                        GNUNET_CONTAINER_PeerMapIterator it,
                                        void *it_cls)
 {
   int count;
-  unsigned int i;
   union MapEntry me;
+  union MapEntry *ce;
   struct GNUNET_PeerIdentity kc;
 
   count = 0;
   GNUNET_assert (NULL != map);
-  for (i = 0; i < map->map_length; i++)
+  ce = &map->next_cache[map->next_cache_off];
+  GNUNET_assert (++map->next_cache_off < NEXT_CACHE_SIZE);
+  for (unsigned int i = 0; i < map->map_length; i++)
   {
     me = map->map[i];
     if (map->use_small_entries)
     {
       struct SmallMapEntry *sme;
-      struct SmallMapEntry *nxt;
 
-      nxt = me.sme;
-      while (NULL != (sme = nxt))
+      ce->sme = me.sme;
+      while (NULL != (sme = ce->sme))
       {
-       nxt = sme->next;
+       ce->sme = sme->next;
        if (NULL != it)
        {
-         if (GNUNET_OK != it (it_cls, sme->key, sme->value))
+         if (GNUNET_OK != it (it_cls,
+                              sme->key,
+                              sme->value))
+         {
+           GNUNET_assert (--map->next_cache_off < NEXT_CACHE_SIZE);
            return GNUNET_SYSERR;
+         }
        }
        count++;
       }
@@ -346,26 +381,65 @@ GNUNET_CONTAINER_multipeermap_iterate (const struct
     else
     {
       struct BigMapEntry *bme;
-      struct BigMapEntry *nxt;
 
-      nxt = me.bme;
-      while (NULL != (bme = nxt))
+      ce->bme = me.bme;
+      while (NULL != (bme = ce->bme))
       {
-       nxt = bme->next;
+       ce->bme = bme->next;
        if (NULL != it)
        {
          kc = bme->key;
-         if (GNUNET_OK != it (it_cls, &kc, bme->value))
+         if (GNUNET_OK != it (it_cls,
+                              &kc,
+                              bme->value))
+         {
+           GNUNET_assert (--map->next_cache_off < NEXT_CACHE_SIZE);
            return GNUNET_SYSERR;
+         }
        }
        count++;
       }
     }
   }
+  GNUNET_assert (--map->next_cache_off < NEXT_CACHE_SIZE);
   return count;
 }
 
 
+/**
+ * We are about to free() the @a bme, make sure it is not in
+ * the list of next values for any iterator in the @a map's next_cache.
+ *
+ * @param map the map to check
+ * @param bme the entry that is about to be free'd
+ */
+static void
+update_next_cache_bme (struct GNUNET_CONTAINER_MultiPeerMap *map,
+                      const struct BigMapEntry *bme)
+{
+  for (unsigned int i=0;i<map->next_cache_off;i++)
+    if (map->next_cache[i].bme == bme)
+      map->next_cache[i].bme = bme->next;
+}
+
+
+/**
+ * We are about to free() the @a sme, make sure it is not in
+ * the list of next values for any iterator in the @a map's next_cache.
+ *
+ * @param map the map to check
+ * @param sme the entry that is about to be free'd
+ */
+static void
+update_next_cache_sme (struct GNUNET_CONTAINER_MultiPeerMap *map,
+                      const struct SmallMapEntry *sme)
+{
+  for (unsigned int i=0;i<map->next_cache_off;i++)
+    if (map->next_cache[i].sme == sme)
+      map->next_cache[i].sme = sme->next;
+}
+
+
 /**
  * Remove the given key-value pair from the map.  Note that if the
  * key-value pair is in the map multiple times, only one of the pairs
@@ -374,7 +448,7 @@ GNUNET_CONTAINER_multipeermap_iterate (const struct
  * @param map the map
  * @param key key of the key-value pair
  * @param value value of the key-value pair
- * @return GNUNET_YES on success, GNUNET_NO if the key-value pair
+ * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
  *  is not in the map
  */
 int
@@ -386,16 +460,13 @@ GNUNET_CONTAINER_multipeermap_remove (struct GNUNET_CONTAINER_MultiPeerMap *map,
   unsigned int i;
 
   map->modification_counter++;
-
   i = idx_of (map, key);
   me = map->map[i];
   if (map->use_small_entries)
   {
-    struct SmallMapEntry *sme;
-    struct SmallMapEntry *p;
+    struct SmallMapEntry *p = NULL;
 
-    p = NULL;
-    for (sme = me.sme; NULL != sme; sme = sme->next)
+    for (struct SmallMapEntry *sme = me.sme; NULL != sme; sme = sme->next)
     {
       if ((0 == memcmp (key, sme->key, sizeof (struct GNUNET_PeerIdentity))) &&
          (value == sme->value))
@@ -404,6 +475,8 @@ GNUNET_CONTAINER_multipeermap_remove (struct GNUNET_CONTAINER_MultiPeerMap *map,
          map->map[i].sme = sme->next;
        else
          p->next = sme->next;
+       update_next_cache_sme (map,
+                              sme);
        GNUNET_free (sme);
        map->size--;
        return GNUNET_YES;
@@ -413,19 +486,21 @@ GNUNET_CONTAINER_multipeermap_remove (struct GNUNET_CONTAINER_MultiPeerMap *map,
   }
   else
   {
-    struct BigMapEntry *bme;
-    struct BigMapEntry *p;
+    struct BigMapEntry *p = NULL;
 
-    p = NULL;
-    for (bme = me.bme; NULL != bme; bme = bme->next)
+    for (struct BigMapEntry *bme = me.bme; NULL != bme; bme = bme->next)
     {
-      if ((0 == memcmp (key, &bme->key, sizeof (struct GNUNET_PeerIdentity))) &&
+      if ((0 == memcmp (key,
+                       &bme->key,
+                       sizeof (struct GNUNET_PeerIdentity))) &&
          (value == bme->value))
       {
        if (NULL == p)
          map->map[i].bme = bme->next;
        else
          p->next = bme->next;
+       update_next_cache_bme (map,
+                              bme);
        GNUNET_free (bme);
        map->size--;
        return GNUNET_YES;
@@ -446,8 +521,8 @@ GNUNET_CONTAINER_multipeermap_remove (struct GNUNET_CONTAINER_MultiPeerMap *map,
  * @return number of values removed
  */
 int
-GNUNET_CONTAINER_multipeermap_remove_all (struct GNUNET_CONTAINER_MultiPeerMap
-                                          *map, const struct GNUNET_PeerIdentity *key)
+GNUNET_CONTAINER_multipeermap_remove_all (struct GNUNET_CONTAINER_MultiPeerMap *map,
+                                         const struct GNUNET_PeerIdentity *key)
 {
   union MapEntry me;
   unsigned int i;
@@ -467,19 +542,23 @@ GNUNET_CONTAINER_multipeermap_remove_all (struct GNUNET_CONTAINER_MultiPeerMap
     sme = me.sme;
     while (NULL != sme)
     {
-      if (0 == memcmp (key, sme->key, sizeof (struct GNUNET_PeerIdentity)))
+      if (0 == memcmp (key,
+                      sme->key,
+                      sizeof (struct GNUNET_PeerIdentity)))
       {
        if (NULL == p)
          map->map[i].sme = sme->next;
        else
          p->next = sme->next;
+       update_next_cache_sme (map,
+                              sme);
        GNUNET_free (sme);
        map->size--;
        if (NULL == p)
          sme = map->map[i].sme;
        else
          sme = p->next;
-       ret++;  
+       ret++;
       }
       else
       {
@@ -497,12 +576,16 @@ GNUNET_CONTAINER_multipeermap_remove_all (struct GNUNET_CONTAINER_MultiPeerMap
     bme = me.bme;
     while (NULL != bme)
     {
-      if (0 == memcmp (key, &bme->key, sizeof (struct GNUNET_PeerIdentity)))
+      if (0 == memcmp (key,
+                      &bme->key,
+                      sizeof (struct GNUNET_PeerIdentity)))
       {
        if (NULL == p)
          map->map[i].bme = bme->next;
        else
          p->next = bme->next;
+       update_next_cache_bme (map,
+                              bme);
        GNUNET_free (bme);
        map->size--;
        if (NULL == p)
@@ -528,12 +611,11 @@ GNUNET_CONTAINER_multipeermap_remove_all (struct GNUNET_CONTAINER_MultiPeerMap
  *
  * @param map the map
  * @param key the key to test if a value exists for it
- * @return GNUNET_YES if such a value exists,
- *         GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ *         #GNUNET_NO if not
  */
 int
-GNUNET_CONTAINER_multipeermap_contains (const struct
-                                        GNUNET_CONTAINER_MultiPeerMap *map,
+GNUNET_CONTAINER_multipeermap_contains (const struct GNUNET_CONTAINER_MultiPeerMap *map,
                                         const struct GNUNET_PeerIdentity *key)
 {
   union MapEntry me;
@@ -541,17 +623,13 @@ GNUNET_CONTAINER_multipeermap_contains (const struct
   me = map->map[idx_of (map, key)];
   if (map->use_small_entries)
   {
-    struct SmallMapEntry *sme;
-
-    for (sme = me.sme; NULL != sme; sme = sme->next)
+    for (struct SmallMapEntry *sme = me.sme; NULL != sme; sme = sme->next)
       if (0 == memcmp (key, sme->key, sizeof (struct GNUNET_PeerIdentity)))
        return GNUNET_YES;
   }
   else
   {
-    struct BigMapEntry *bme;
-
-    for (bme = me.bme; NULL != bme; bme = bme->next)
+    for (struct BigMapEntry *bme = me.bme; NULL != bme; bme = bme->next)
       if (0 == memcmp (key, &bme->key, sizeof (struct GNUNET_PeerIdentity)))
        return GNUNET_YES;
   }
@@ -566,13 +644,12 @@ GNUNET_CONTAINER_multipeermap_contains (const struct
  * @param map the map
  * @param key the key to test if a value exists for it
  * @param value value to test for
- * @return GNUNET_YES if such a value exists,
- *         GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ *         #GNUNET_NO if not
  */
 int
-GNUNET_CONTAINER_multipeermap_contains_value (const struct
-                                              GNUNET_CONTAINER_MultiPeerMap
-                                              *map, const struct GNUNET_PeerIdentity *key,
+GNUNET_CONTAINER_multipeermap_contains_value (const struct GNUNET_CONTAINER_MultiPeerMap *map,
+                                             const struct GNUNET_PeerIdentity *key,
                                               const void *value)
 {
   union MapEntry me;
@@ -580,19 +657,19 @@ GNUNET_CONTAINER_multipeermap_contains_value (const struct
   me = map->map[idx_of (map, key)];
   if (map->use_small_entries)
   {
-    struct SmallMapEntry *sme;
-
-    for (sme = me.sme; NULL != sme; sme = sme->next)
-      if ( (0 == memcmp (key, sme->key, sizeof (struct GNUNET_PeerIdentity))) &&
+    for (struct SmallMapEntry *sme = me.sme; NULL != sme; sme = sme->next)
+      if ( (0 == memcmp (key,
+                        sme->key,
+                        sizeof (struct GNUNET_PeerIdentity))) &&
           (sme->value == value) )
        return GNUNET_YES;
   }
   else
   {
-    struct BigMapEntry *bme;
-
-    for (bme = me.bme; NULL != bme; bme = bme->next)
-      if ( (0 == memcmp (key, &bme->key, sizeof (struct GNUNET_PeerIdentity))) &&
+    for (struct BigMapEntry *bme = me.bme; NULL != bme; bme = bme->next)
+      if ( (0 == memcmp (key,
+                        &bme->key,
+                        sizeof (struct GNUNET_PeerIdentity))) &&
           (bme->value == value) )
        return GNUNET_YES;
   }
@@ -613,17 +690,23 @@ grow (struct GNUNET_CONTAINER_MultiPeerMap *map)
   unsigned int old_len;
   unsigned int new_len;
   unsigned int idx;
-  unsigned int i;
-
-  map->modification_counter++;
 
   old_map = map->map;
   old_len = map->map_length;
+  GNUNET_assert (0 != old_len);
   new_len = old_len * 2;
-  new_map = GNUNET_malloc (sizeof (union MapEntry) * new_len);
+  if (0 == new_len) /* 2^31 * 2 == 0 */
+    new_len = old_len; /* never use 0 */
+  if (new_len == old_len)
+    return; /* nothing changed */
+  new_map = GNUNET_malloc_large (new_len *
+                                 sizeof (union MapEntry));
+  if (NULL == new_map)
+    return; /* grow not possible */
+  map->modification_counter++;
   map->map_length = new_len;
   map->map = new_map;
-  for (i = 0; i < old_len; i++)
+  for (unsigned int i = 0; i < old_len; i++)
   {
     if (map->use_small_entries)
     {
@@ -642,7 +725,7 @@ grow (struct GNUNET_CONTAINER_MultiPeerMap *map)
       struct BigMapEntry *bme;
 
       while (NULL != (bme = old_map[i].bme))
-      {        
+      {
        old_map[i].bme = bme->next;
        idx = idx_of (map, &bme->key);
        bme->next = new_map[idx].bme;
@@ -663,7 +746,7 @@ grow (struct GNUNET_CONTAINER_MultiPeerMap *map)
  * @param opt options for put
  * @return #GNUNET_OK on success,
  *         #GNUNET_NO if a value was replaced (with REPLACE)
- *         #GNUNET_SYSERR if GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY was the option and the
+ *         #GNUNET_SYSERR if #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY was the option and the
  *                       value already exists
  */
 int
@@ -748,52 +831,144 @@ GNUNET_CONTAINER_multipeermap_put (struct GNUNET_CONTAINER_MultiPeerMap *map,
  *         #GNUNET_SYSERR if it aborted iteration
  */
 int
-GNUNET_CONTAINER_multipeermap_get_multiple (const struct GNUNET_CONTAINER_MultiPeerMap *map,
+GNUNET_CONTAINER_multipeermap_get_multiple (struct GNUNET_CONTAINER_MultiPeerMap *map,
                                             const struct GNUNET_PeerIdentity *key,
                                             GNUNET_CONTAINER_PeerMapIterator it,
                                             void *it_cls)
 {
   int count;
   union MapEntry me;
+  union MapEntry *ce;
 
+  ce = &map->next_cache[map->next_cache_off];
+  GNUNET_assert (++map->next_cache_off < NEXT_CACHE_SIZE);
   count = 0;
   me = map->map[idx_of (map, key)];
   if (map->use_small_entries)
   {
     struct SmallMapEntry *sme;
-    struct SmallMapEntry *nxt;
 
-    nxt = me.sme;
-    while (NULL != (sme = nxt))
+    ce->sme = me.sme;
+    while (NULL != (sme = ce->sme))
     {
-      nxt = sme->next;
-      if (0 != memcmp (key, sme->key, sizeof (struct GNUNET_PeerIdentity)))
+      ce->sme = sme->next;
+      if (0 != memcmp (key,
+                      sme->key,
+                      sizeof (struct GNUNET_PeerIdentity)))
        continue;
-      if ((it != NULL) && (GNUNET_OK != it (it_cls, key, sme->value)))
+      if ( (NULL != it) &&
+          (GNUNET_OK != it (it_cls,
+                            key,
+                            sme->value)))
+      {
+       GNUNET_assert (--map->next_cache_off < NEXT_CACHE_SIZE);
        return GNUNET_SYSERR;
+      }
       count++;
     }
   }
   else
   {
     struct BigMapEntry *bme;
-    struct BigMapEntry *nxt;
 
-    nxt = me.bme;
-    while (NULL != (bme = nxt))
+    ce->bme = me.bme;
+    while (NULL != (bme = ce->bme))
     {
-      nxt = bme->next;
-      if (0 != memcmp (key, &bme->key, sizeof (struct GNUNET_PeerIdentity)))
+      ce->bme = bme->next;
+      if (0 != memcmp (key,
+                      &bme->key,
+                      sizeof (struct GNUNET_PeerIdentity)))
        continue;
-      if ((it != NULL) && (GNUNET_OK != it (it_cls, key, bme->value)))
+      if ( (NULL != it) &&
+          (GNUNET_OK != it (it_cls,
+                            key,
+                            bme->value)))
+      {
+       GNUNET_assert (--map->next_cache_off < NEXT_CACHE_SIZE);
        return GNUNET_SYSERR;
+      }
       count++;
     }
   }
+  GNUNET_assert (--map->next_cache_off < NEXT_CACHE_SIZE);
   return count;
 }
 
 
+/**
+ * @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_multipeermap_get_random (const struct GNUNET_CONTAINER_MultiPeerMap *map,
+                                          GNUNET_CONTAINER_PeerMapIterator it,
+                                          void *it_cls)
+{
+  unsigned int off;
+  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 (unsigned int 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 multipeermap.
  * The iterator can be used to retrieve all the elements in the multipeermap