src/testbed/gnunet-service-testbed_connectionpool.c

   1 /*
   2   This file is part of GNUnet.
   3   (C) 2008--2013 Christian Grothoff (and other contributing authors)
   4
   5   GNUnet is free software; you can redistribute it and/or modify
   6   it under the terms of the GNU General Public License as published
   7   by the Free Software Foundation; either version 3, or (at your
   8   option) any later version.
   9
  10   GNUnet is distributed in the hope that it will be useful, but
  11   WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13   General Public License for more details.
  14
  15   You should have received a copy of the GNU General Public License
  16   along with GNUnet; see the file COPYING.  If not, write to the
  17   Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18   Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file testbed/gnunet-service-testbed_connectionpool.c
  23  * @brief connection pooling for connections to peers' services
  24  * @author Sree Harsha Totakura <sreeharsha@totakura.in>
  25  */
  26
  27 #include "gnunet-service-testbed.h"
  28 #include "gnunet-service-testbed_connectionpool.h"
  29 #include "testbed_api_operations.h"
  30
  31 /**
  32  * Redefine LOG with a changed log component string
  33  */
  34 #ifdef LOG
  35 #undef LOG
  36 #endif
  37 #define LOG(kind,...)                                   \
  38   GNUNET_log_from (kind, "testbed-connectionpool", __VA_ARGS__)
  39
  40
  41 /**
  42  * Time to expire a cache entry
  43  */
  44 #define CACHE_EXPIRY                            \
  45   GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 15)
  46
  47
  48 /**
  49  * The request handle for obtaining a pooled connection
  50  */
  51 struct GST_ConnectionPool_GetHandle;
  52
  53
  54 /**
  55  * A pooled connection
  56  */
  57 struct PooledConnection
  58 {
  59   /**
  60    * Next ptr for placing this object in the DLL of least recently used pooled
  61    * connections
  62    */
  63   struct PooledConnection *next;
  64
  65   /**
  66    * Prev ptr for placing this object in the DLL of the least recently used
  67    * pooled connections
  68    */
  69   struct PooledConnection *prev;
  70
  71   /**
  72    * The transport handle to the peer corresponding to this entry; can be NULL
  73    */
  74   struct GNUNET_TRANSPORT_Handle *handle_transport;
  75
  76   /**
  77    * The core handle to the peer corresponding to this entry; can be NULL
  78    */
  79   struct GNUNET_CORE_Handle *handle_core;
  80
  81   /**
  82    * The operation handle for transport handle
  83    */
  84   struct GNUNET_TESTBED_Operation *op_transport;
  85
  86   /**
  87    * The operation handle for core handle
  88    */
  89   struct GNUNET_TESTBED_Operation *op_core;
  90
  91   /**
  92    * The peer identity of this peer. Will be set upon opening a connection to
  93    * the peers CORE service. Will be NULL until then and after the CORE
  94    * connection is closed
  95    */
  96   struct GNUNET_PeerIdentity *peer_identity;
  97
  98   /**
  99    * The configuration of the peer. Should be not NULL as long as the core_handle
 100    * or transport_handle are valid
 101    */
 102   struct GNUNET_CONFIGURATION_Handle *cfg;
 103
 104   /**
 105    * DLL head for the queue to serve notifications when a peer is connected
 106    */
 107   struct GST_ConnectionPool_GetHandle *head_notify;
 108
 109   /**
 110    * DLL tail for the queue to serve notifications when a peer is connected
 111    */
 112   struct GST_ConnectionPool_GetHandle *tail_notify;
 113
 114   /**
 115    * DLL head for the queue of #GST_ConnectionPool_GetHandle requests that are
 116    * waiting for this connection to be opened
 117    */
 118   struct GST_ConnectionPool_GetHandle *head_waiting;
 119
 120   /**
 121    * DLL tail for the queue of #GST_ConnectionPool_GetHandle requests that are
 122    * waiting for this connection to be opened
 123    */
 124   struct GST_ConnectionPool_GetHandle *tail_waiting;
 125
 126   /**
 127    * The task to expire this connection from the connection pool
 128    */
 129   GNUNET_SCHEDULER_TaskIdentifier expire_task;
 130
 131   /**
 132    * The task to notify a waiting #GST_ConnectionPool_GetHandle object
 133    */
 134   GNUNET_SCHEDULER_TaskIdentifier notify_task;
 135
 136   /**
 137    * Number of active requests using this pooled connection
 138    */
 139   unsigned int demand;
 140
 141   /**
 142    * Is this entry in LRU
 143    */
 144   int in_lru;
 145
 146   /**
 147    * Is this entry present in the connection pool
 148    */
 149   int in_pool;
 150
 151   /**
 152    * The index of this peer
 153    */
 154   uint32_t index;
 155 };
 156
 157
 158 /**
 159  * The request handle for obtaining a pooled connection
 160  */
 161 struct GST_ConnectionPool_GetHandle
 162 {
 163   /**
 164    * The next ptr for inclusion in the notification DLLs.  At first the object
 165    * is placed in the waiting DLL of the corresponding #PooledConnection
 166    * object.  After the handle is opened it is moved to the notification DLL if
 167    * @p connect_notify_cb and @p target are not NULL
 168    */
 169   struct GST_ConnectionPool_GetHandle *next;
 170
 171   /**
 172    * The prev ptr for inclusion in the notification DLLs
 173    */
 174   struct GST_ConnectionPool_GetHandle *prev;
 175
 176   /**
 177    * The pooled connection object this handle corresponds to
 178    */
 179   struct PooledConnection *entry;
 180
 181   /**
 182    * The cache callback to call when a handle is available
 183    */
 184   GST_connection_pool_connection_ready_cb cb;
 185
 186   /**
 187    * The closure for the above callback
 188    */
 189   void *cb_cls;
 190
 191   /**
 192    * The peer identity of the target peer. When this target peer is connected,
 193    * call the notify callback
 194    */
 195   const struct GNUNET_PeerIdentity *target;
 196
 197   /**
 198    * The callback to be called for serving notification that the target peer is
 199    * connected
 200    */
 201   GST_connection_pool_peer_connect_notify connect_notify_cb;
 202
 203   /**
 204    * The closure for the notify callback
 205    */
 206   void *connect_notify_cb_cls;
 207
 208   /**
 209    * The service we want to connect to
 210    */
 211   enum GST_ConnectionPool_Service service;
 212
 213   /**
 214    * Did we call the pool_connection_ready_cb already?
 215    */
 216   int connection_ready_called;
 217 };
 218
 219
 220 /**
 221  * A hashmap for quickly finding connections in the connection pool
 222  */
 223 static struct GNUNET_CONTAINER_MultiHashMap32 *map;
 224
 225 /**
 226  * DLL head for maitaining the least recently used #PooledConnection objects.
 227  * The head is the least recently used object.
 228  */
 229 static struct PooledConnection *head_lru;
 230
 231 /**
 232  * DLL tail for maitaining the least recently used #PooledConnection objects
 233  */
 234 static struct PooledConnection *tail_lru;
 235
 236 /**
 237  * DLL head for maintaining #PooledConnection objects that are not added into
 238  * the connection pool as it was full at the time the object's creation
 239  * FIXME
 240  */
 241 static struct PooledConnection *head_not_pooled;
 242
 243 /**
 244  * DLL tail for maintaining #PooledConnection objects that are not added into
 245  * the connection pool as it was full at the time the object's creation
 246  */
 247 static struct PooledConnection *tail_not_pooled;
 248
 249 /**
 250  * The maximum number of entries that can be present in the connection pool
 251  */
 252 static unsigned int max_size;
 253
 254
 255 /**
 256  * Destroy a #PooledConnection object
 257  *
 258  * @param entry the #PooledConnection object
 259  */
 260 static void
 261 destroy_pooled_connection (struct PooledConnection *entry)
 262 {
 263   GNUNET_assert ((NULL == entry->head_notify) && (NULL == entry->tail_notify));
 264   GNUNET_assert ((NULL == entry->head_waiting) && (NULL ==
 265                                                    entry->tail_waiting));
 266   GNUNET_assert (0 == entry->demand);
 267   GNUNET_free_non_null (entry->peer_identity);
 268   if (entry->in_lru)
 269     GNUNET_CONTAINER_DLL_remove (head_lru, tail_lru, entry);
 270   if (entry->in_pool)
 271     GNUNET_assert (GNUNET_OK ==
 272                    GNUNET_CONTAINER_multihashmap32_remove (map,
 273                                                            entry->index,
 274                                                            entry));
 275   LOG_DEBUG ("Cleaning up handles of a pooled connection\n");
 276   if (NULL != entry->handle_transport)
 277     GNUNET_assert (NULL != entry->op_transport);
 278   if (NULL != entry->op_transport)
 279   {
 280     GNUNET_TESTBED_operation_done (entry->op_transport);
 281     entry->op_transport = NULL;
 282   }
 283   if (NULL != entry->op_core)
 284   {
 285     GNUNET_TESTBED_operation_done (entry->op_core);
 286     entry->op_core = NULL;
 287   }
 288   GNUNET_assert (NULL == entry->handle_core);
 289   GNUNET_assert (NULL == entry->handle_transport);
 290   GNUNET_CONFIGURATION_destroy (entry->cfg);
 291   GNUNET_free (entry);
 292 }
 293
 294
 295 /**
 296  * Expire a #PooledConnection object
 297  *
 298  * @param cls the #PooledConnection object
 299  * @param tc scheduler task context
 300  */
 301 static void
 302 expire (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 303 {
 304   struct PooledConnection *entry = cls;
 305
 306   entry->expire_task = GNUNET_SCHEDULER_NO_TASK;
 307   destroy_pooled_connection (entry);
 308 }
 309
 310
 311 static void
 312 expire_task_cancel (struct PooledConnection *entry)
 313 {
 314   if (GNUNET_SCHEDULER_NO_TASK != entry->expire_task)
 315   {
 316     GNUNET_SCHEDULER_cancel (entry->expire_task);
 317     entry->expire_task = GNUNET_SCHEDULER_NO_TASK;
 318   }
 319 }
 320
 321
 322 /**
 323  * Function to add a #PooledConnection object into LRU and begin the expiry task
 324  *
 325  * @param entry the #PooledConnection object
 326  */
 327 static void
 328 add_to_lru (struct PooledConnection *entry)
 329 {
 330   GNUNET_assert (0 == entry->demand);
 331   GNUNET_assert (!entry->in_lru);
 332   GNUNET_CONTAINER_DLL_insert_tail (head_lru, tail_lru, entry);
 333   entry->in_lru = GNUNET_YES;
 334   GNUNET_assert (GNUNET_SCHEDULER_NO_TASK == entry->expire_task);
 335   entry->expire_task = GNUNET_SCHEDULER_add_delayed (CACHE_EXPIRY,
 336                                                      &expire, entry);
 337 }
 338
 339
 340 /**
 341  * Function to find a #GST_ConnectionPool_GetHandle which is waiting for one of
 342  * the handles in given entry which are now available.
 343  *
 344  * @param entry the pooled connection whose active list has to be searched
 345  * @param head the starting list element in the GSTCacheGetHandle where the
 346  *          search has to be begin
 347  * @return a suitable GSTCacheGetHandle whose handle ready notify callback
 348  *           hasn't been called yet. NULL if no such suitable GSTCacheGetHandle
 349  *           is found
 350  */
 351 static struct GST_ConnectionPool_GetHandle *
 352 search_waiting (const struct PooledConnection *entry,
 353                 struct GST_ConnectionPool_GetHandle *head)
 354 {
 355   struct GST_ConnectionPool_GetHandle *gh;
 356
 357   for (gh = head; NULL != gh; gh = gh->next)
 358   {
 359     switch (gh->service)
 360     {
 361     case GST_CONNECTIONPOOL_SERVICE_CORE:
 362       if (NULL == entry->handle_core)
 363         continue;
 364       if (NULL == entry->peer_identity)
 365         continue;               /* CORE connection isn't ready yet */
 366       break;
 367     case GST_CONNECTIONPOOL_SERVICE_TRANSPORT:
 368       if (NULL == entry->handle_transport)
 369         continue;
 370       break;
 371     }
 372     break;
 373   }
 374   return gh;
 375 }
 376
 377
 378 /**
 379  * A handle in the #PooledConnection object pointed by @a cls is ready and there
 380  * is a #GST_ConnectionPool_GetHandle object waiting in the waiting list.  This
 381  * function retrieves that object and calls the handle ready callback.  It
 382  * further schedules itself if there are similar waiting objects which can be notified.
 383  *
 384  * @param cls the #PooledConnection object
 385  * @param tc the task context from scheduler
 386  */
 387 static void
 388 connection_ready (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 389 {
 390   struct PooledConnection *entry = cls;
 391   struct GST_ConnectionPool_GetHandle *gh;
 392   struct GST_ConnectionPool_GetHandle *gh_next;
 393
 394   GNUNET_assert (GNUNET_SCHEDULER_NO_TASK != entry->notify_task);
 395   entry->notify_task = GNUNET_SCHEDULER_NO_TASK;
 396   gh = search_waiting (entry, entry->head_waiting);
 397   GNUNET_assert (NULL != gh);
 398   gh_next = NULL;
 399   if (NULL != gh->next)
 400     gh_next = search_waiting (entry, gh->next);
 401   GNUNET_CONTAINER_DLL_remove (entry->head_waiting, entry->tail_waiting, gh);
 402   gh->connection_ready_called = GNUNET_YES;
 403   if (NULL != gh_next)
 404     entry->notify_task = GNUNET_SCHEDULER_add_now (&connection_ready, entry);
 405   if ( (NULL != gh->target) && (NULL != gh->connect_notify_cb) )
 406     GNUNET_CONTAINER_DLL_insert_tail (entry->head_notify, entry->tail_notify, gh);
 407   LOG_DEBUG ("Calling notify for handle type %u\n", gh->service);
 408   gh->cb (gh->cb_cls, entry->handle_core, entry->handle_transport,
 409           entry->peer_identity);
 410 }
 411
 412
 413 /**
 414  * Function called from peer connect notify callbacks from CORE and TRANSPORT
 415  * connections. This function calls the pendning peer connect notify callbacks
 416  * which are queued in an entry.
 417  *
 418  * @param cls the #PooledConnection object
 419  * @param peer the peer that connected
 420  * @param service the service where this notification has originated
 421  */
 422 static void
 423 peer_connect_notify_cb (void *cls, const struct GNUNET_PeerIdentity *peer,
 424                         const enum GST_ConnectionPool_Service service)
 425 {
 426   struct PooledConnection *entry = cls;
 427   struct GST_ConnectionPool_GetHandle *gh;
 428   struct GST_ConnectionPool_GetHandle *gh_next;
 429   GST_connection_pool_peer_connect_notify cb;
 430   void *cb_cls;
 431
 432   for (gh = entry->head_notify; NULL != gh;)
 433   {
 434     GNUNET_assert (NULL != gh->target);
 435     GNUNET_assert (NULL != gh->connect_notify_cb);
 436     GNUNET_assert (gh->connection_ready_called);
 437     if (service != gh->service)
 438     {
 439       gh = gh->next;
 440       continue;
 441     }
 442     if (0 != memcmp (gh->target, peer, sizeof (struct GNUNET_PeerIdentity)))
 443     {
 444       gh = gh->next;
 445       continue;
 446     }
 447     cb = gh->connect_notify_cb;
 448     cb_cls = gh->connect_notify_cb_cls;
 449     gh_next = gh->next;
 450     GNUNET_CONTAINER_DLL_remove (entry->head_notify, entry->tail_notify, gh);
 451     gh = gh_next;
 452     cb (cb_cls, peer);
 453   }
 454 }
 455
 456
 457 /**
 458  * Function called to notify transport users that another
 459  * peer connected to us.
 460  *
 461  * @param cls the #PooledConnection object
 462  * @param peer the peer that connected
 463  */
 464 static void
 465 transport_peer_connect_notify_cb (void *cls,
 466                                   const struct GNUNET_PeerIdentity *peer)
 467 {
 468   struct PooledConnection *entry = cls;
 469
 470   peer_connect_notify_cb (entry, peer, GST_CONNECTIONPOOL_SERVICE_TRANSPORT);
 471 }
 472
 473
 474 /**
 475  * Function called when resources for opening a connection to TRANSPORT are
 476  * available.
 477  *
 478  * @param cls the #PooledConnection object
 479  */
 480 static void
 481 opstart_get_handle_transport (void *cls)
 482 {
 483   struct PooledConnection *entry = cls;
 484
 485   GNUNET_assert (NULL != entry);
 486   LOG_DEBUG ("Opening a transport connection to peer %u\n", entry->index);
 487   entry->handle_transport =
 488       GNUNET_TRANSPORT_connect (entry->cfg, NULL, entry, NULL,
 489                                 &transport_peer_connect_notify_cb, NULL);
 490   if (NULL == entry->handle_transport)
 491   {
 492     GNUNET_break (0);
 493     return;
 494   }
 495   if (0 == entry->demand)
 496     return;
 497   if (GNUNET_SCHEDULER_NO_TASK != entry->notify_task)
 498     return;
 499   if (NULL != search_waiting (entry, entry->head_waiting))
 500   {
 501     entry->notify_task = GNUNET_SCHEDULER_add_now (&connection_ready, entry);
 502     return;
 503   }
 504 }
 505
 506
 507 /**
 508  * Function called when the operation responsible for opening a TRANSPORT
 509  * connection is marked as done.
 510  *
 511  * @param cls the cache entry
 512  */
 513 static void
 514 oprelease_get_handle_transport (void *cls)
 515 {
 516   struct PooledConnection *entry = cls;
 517
 518   if (NULL == entry->handle_transport)
 519     return;
 520   GNUNET_TRANSPORT_disconnect (entry->handle_transport);
 521   entry->handle_transport = NULL;
 522 }
 523
 524
 525 /**
 526  * Method called whenever a given peer connects at CORE level
 527  *
 528  * @param cls the #PooledConnection object
 529  * @param peer peer identity this notification is about
 530  */
 531 static void
 532 core_peer_connect_cb (void *cls, const struct GNUNET_PeerIdentity *peer)
 533 {
 534   struct PooledConnection *entry = cls;
 535
 536   peer_connect_notify_cb (entry, peer, GST_CONNECTIONPOOL_SERVICE_CORE);
 537 }
 538
 539
 540 /**
 541  * Function called after GNUNET_CORE_connect has succeeded (or failed
 542  * for good).  Note that the private key of the peer is intentionally
 543  * not exposed here; if you need it, your process should try to read
 544  * the private key file directly (which should work if you are
 545  * authorized...).  Implementations of this function must not call
 546  * GNUNET_CORE_disconnect (other than by scheduling a new task to
 547  * do this later).
 548  *
 549  * @param cls the #PooledConnection object
 550  * @param my_identity ID of this peer, NULL if we failed
 551  */
 552 static void
 553 core_startup_cb (void *cls,
 554                  const struct GNUNET_PeerIdentity *my_identity)
 555 {
 556   struct PooledConnection *entry = cls;
 557
 558   if (NULL == my_identity)
 559   {
 560     GNUNET_break (0);
 561     return;
 562   }
 563   GNUNET_assert (NULL == entry->peer_identity);
 564   entry->peer_identity = GNUNET_new (struct GNUNET_PeerIdentity);
 565   memcpy (entry->peer_identity,
 566           my_identity,
 567           sizeof (struct GNUNET_PeerIdentity));
 568   if (0 == entry->demand)
 569     return;
 570   if (GNUNET_SCHEDULER_NO_TASK != entry->notify_task)
 571     return;
 572   if (NULL != search_waiting (entry, entry->head_waiting))
 573   {
 574     entry->notify_task = GNUNET_SCHEDULER_add_now (&connection_ready, entry);
 575     return;
 576   }
 577 }
 578
 579
 580 /**
 581  * Function called when resources for opening a connection to CORE are
 582  * available.
 583  *
 584  * @param cls the #PooledConnection object
 585  */
 586 static void
 587 opstart_get_handle_core (void *cls)
 588 {
 589   struct PooledConnection *entry = cls;
 590   const struct GNUNET_CORE_MessageHandler no_handlers[] = {
 591     {NULL, 0, 0}
 592   };
 593
 594   GNUNET_assert (NULL != entry);
 595   LOG_DEBUG ("Opening a CORE connection to peer %u\n", entry->index);
 596   entry->handle_core =
 597       GNUNET_CORE_connect (entry->cfg, entry,        /* closure */
 598                            &core_startup_cb, /* core startup notify */
 599                            &core_peer_connect_cb,    /* peer connect notify */
 600                            NULL,     /* peer disconnect notify */
 601                            NULL,     /* inbound notify */
 602                            GNUNET_NO,        /* inbound header only? */
 603                            NULL,     /* outbound notify */
 604                            GNUNET_NO,        /* outbound header only? */
 605                            no_handlers);
 606 }
 607
 608
 609 /**
 610  * Function called when the operation responsible for opening a TRANSPORT
 611  * connection is marked as done.
 612  *
 613  * @param cls the #PooledConnection object
 614  */
 615 static void
 616 oprelease_get_handle_core (void *cls)
 617 {
 618   struct PooledConnection *entry = cls;
 619
 620   if (NULL == entry->handle_core)
 621     return;
 622   GNUNET_CORE_disconnect (entry->handle_core);
 623   entry->handle_core = NULL;
 624   GNUNET_free_non_null (entry->peer_identity);
 625   entry->peer_identity = NULL;
 626 }
 627
 628
 629 /**
 630  * This function will be called for every #PooledConnection object in @p map
 631  *
 632  * @param cls NULL
 633  * @param key current key code
 634  * @param value the #PooledConnection object
 635  * @return #GNUNET_YES if we should continue to
 636  *         iterate,
 637  *         #GNUNET_NO if not.
 638  */
 639 static int
 640 cleanup_iterator (void *cls,
 641                   uint32_t key,
 642                   void *value)
 643 {
 644   struct PooledConnection *entry = value;
 645
 646   GNUNET_assert (NULL != entry);
 647   GNUNET_assert (GNUNET_OK ==
 648                  GNUNET_CONTAINER_multihashmap32_remove (map, key, entry));
 649   if (entry->in_lru)
 650     GNUNET_CONTAINER_DLL_remove (head_lru, tail_lru, entry);
 651   destroy_pooled_connection (entry);
 652   return GNUNET_YES;
 653 }
 654
 655
 656 /**
 657  * Initialise the connection pool.
 658  *
 659  * @param size the size of the connection pool.  Each entry in the connection
 660  *   pool can handle a connection to each of the services enumerated in
 661  *   #GST_ConnectionPool_Service
 662  */
 663 void
 664 GST_connection_pool_init (unsigned int size)
 665 {
 666   max_size = size;
 667   if (0 == max_size)
 668     return;
 669   GNUNET_assert (NULL == map);
 670   map = GNUNET_CONTAINER_multihashmap32_create (((size * 3) / 4) + 1);
 671 }
 672
 673
 674 /**
 675  * Cleanup the connection pool
 676  */
 677 void
 678 GST_connection_pool_destroy ()
 679 {
 680   struct PooledConnection *entry;
 681
 682   if (NULL != map)
 683   {
 684     GNUNET_assert (GNUNET_SYSERR !=
 685                    GNUNET_CONTAINER_multihashmap32_iterate (map,
 686                                                             &cleanup_iterator,
 687                                                             NULL));
 688     GNUNET_CONTAINER_multihashmap32_destroy (map);
 689     map = NULL;
 690   }
 691   while (NULL != (entry = head_lru))
 692   {
 693     GNUNET_CONTAINER_DLL_remove (head_lru, tail_lru, entry);
 694     destroy_pooled_connection (entry);
 695   }
 696 }
 697
 698
 699 /**
 700  * Get a connection handle to @a service.  If the connection is opened before
 701  * and the connection handle is present in the connection pool, it is returned
 702  * through @a cb.  @a peer_id is used for the lookup in the connection pool.  If
 703  * the connection handle is not present in the connection pool, a new connection
 704  * handle is opened for the @a service using @a cfg.  Additionally, @a target,
 705  * @a connect_notify_cb can be specified to get notified when @a target is
 706  * connected at @a service.
 707  *
 708  * @note @a connect_notify_cb will not be called if @a target is
 709  * already connected @a service level. Use
 710  * GNUNET_TRANSPORT_check_neighbour_connected() or a similar function from the
 711  * respective @a service's API to check if the target peer is already connected or
 712  * not. @a connect_notify_cb will be called only once or never (in case @a target
 713  * cannot be connected or is already connected).
 714  *
 715  * @param peer_id the index of the peer
 716  * @param cfg the configuration with which the transport handle has to be
 717  *          created if it was not present in the cache
 718  * @param service the service of interest
 719  * @param cb the callback to notify when the transport handle is available
 720  * @param cb_cls the closure for @a cb
 721  * @param target the peer identify of the peer whose connection to our TRANSPORT
 722  *          subsystem will be notified through the @a connect_notify_cb. Can be NULL
 723  * @param connect_notify_cb the callback to call when the @a target peer is
 724  *          connected. This callback will only be called once or never again (in
 725  *          case the target peer cannot be connected). Can be NULL
 726  * @param connect_notify_cb_cls the closure for @a connect_notify_cb
 727  * @return the handle which can be used cancel or mark that the handle is no
 728  *           longer being used
 729  */
 730 struct GST_ConnectionPool_GetHandle *
 731 GST_connection_pool_get_handle (unsigned int peer_id,
 732                                 const struct GNUNET_CONFIGURATION_Handle *cfg,
 733                                 enum GST_ConnectionPool_Service service,
 734                                 GST_connection_pool_connection_ready_cb cb,
 735                                 void *cb_cls,
 736                                 const struct GNUNET_PeerIdentity *target,
 737                                 GST_connection_pool_peer_connect_notify connect_notify_cb,
 738                                 void *connect_notify_cb_cls)
 739 {
 740   struct GST_ConnectionPool_GetHandle *gh;
 741   struct PooledConnection *entry;
 742   struct GNUNET_TESTBED_Operation *op;
 743   void *handle;
 744   uint32_t peer_id32;
 745
 746   peer_id32 = (uint32_t) peer_id;
 747   entry = NULL;
 748   if (NULL != map)
 749     entry = GNUNET_CONTAINER_multihashmap32_get (map, peer_id32);
 750   if (NULL != entry)
 751   {
 752     if (entry->in_lru)
 753     {
 754       GNUNET_assert (0 == entry->demand);
 755       expire_task_cancel (entry);
 756       GNUNET_CONTAINER_DLL_remove (head_lru, tail_lru, entry);
 757       entry->in_lru = GNUNET_NO;
 758     }
 759     switch (service)
 760     {
 761     case GST_CONNECTIONPOOL_SERVICE_TRANSPORT:
 762       handle = entry->handle_transport;
 763       if (NULL != handle)
 764         LOG_DEBUG ("Found TRANSPORT handle for peer %u\n",
 765                    entry->index);
 766       break;
 767     case GST_CONNECTIONPOOL_SERVICE_CORE:
 768       handle = entry->handle_core;
 769       if (NULL != handle)
 770         LOG_DEBUG ("Found CORE handle for peer %u\n",
 771                    entry->index);
 772       break;
 773     }
 774   }
 775   else
 776   {
 777     entry = GNUNET_new (struct PooledConnection);
 778     entry->index = peer_id32;
 779     if ((NULL != map)
 780         && (GNUNET_CONTAINER_multihashmap32_size (map) < max_size))
 781     {
 782       GNUNET_assert (GNUNET_OK ==
 783                      GNUNET_CONTAINER_multihashmap32_put (map,
 784                                                           entry->index,
 785                                                           entry,
 786                                                           GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_FAST));
 787       entry->in_pool = GNUNET_YES;
 788     }
 789     else
 790     {
 791       GNUNET_CONTAINER_DLL_insert_tail (head_not_pooled, tail_not_pooled, entry);
 792     }
 793     entry->cfg = GNUNET_CONFIGURATION_dup (cfg);
 794   }
 795   entry->demand++;
 796   gh = GNUNET_new (struct GST_ConnectionPool_GetHandle);
 797   gh->entry = entry;
 798   gh->cb = cb;
 799   gh->cb_cls = cb_cls;
 800   gh->target = target;
 801   gh->connect_notify_cb = connect_notify_cb;
 802   gh->connect_notify_cb_cls = connect_notify_cb_cls;
 803   gh->service = service;
 804   GNUNET_CONTAINER_DLL_insert (entry->head_waiting, entry->tail_waiting, gh);
 805   if (NULL != handle)
 806   {
 807     if (GNUNET_SCHEDULER_NO_TASK == entry->notify_task)
 808     {
 809       if (NULL != search_waiting (entry, entry->head_waiting))
 810         entry->notify_task = GNUNET_SCHEDULER_add_now (&connection_ready, entry);
 811     }
 812     return gh;
 813   }
 814   op = NULL;
 815   switch (gh->service)
 816   {
 817   case GST_CONNECTIONPOOL_SERVICE_TRANSPORT:
 818     if (NULL != entry->op_transport)
 819       return gh;                /* Operation pending */
 820     op = GNUNET_TESTBED_operation_create_ (entry, &opstart_get_handle_transport,
 821                                            &oprelease_get_handle_transport);
 822     entry->op_transport = op;
 823     break;
 824   case GST_CONNECTIONPOOL_SERVICE_CORE:
 825     if (NULL != entry->op_core)
 826       return gh;                /* Operation pending */
 827     op = GNUNET_TESTBED_operation_create_ (entry, &opstart_get_handle_core,
 828                                            &oprelease_get_handle_core);
 829     entry->op_core = op;
 830     break;
 831   }
 832   GNUNET_TESTBED_operation_queue_insert_ (GST_opq_openfds, op);
 833   GNUNET_TESTBED_operation_begin_wait_ (op);
 834   return gh;
 835 }
 836
 837
 838 /**
 839  * Relinquish a #GST_ConnectionPool_GetHandle object.  If the connection
 840  * associated with the object is currently being used by other
 841  * #GST_ConnectionPool_GetHandle objects, it is left in the connection pool.  If
 842  * no other objects are using the connection and the connection pool is not full
 843  * then it is placed in a LRU queue.  If the connection pool is full, then
 844  * connections from the LRU queue are evicted and closed to create place for this
 845  * connection.  If the connection pool if full and the LRU queue is empty, then
 846  * the connection is closed.
 847  *
 848  * @param gh the handle
 849  */
 850 void
 851 GST_connection_pool_get_handle_done (struct GST_ConnectionPool_GetHandle *gh)
 852 {
 853   struct PooledConnection *entry;
 854
 855   entry = gh->entry;
 856   if (!gh->connection_ready_called)
 857     GNUNET_CONTAINER_DLL_remove (entry->head_waiting, entry->tail_waiting, gh);
 858   else if ((NULL != gh->next) || (NULL != gh->prev))
 859     GNUNET_CONTAINER_DLL_remove (entry->head_notify, entry->head_notify, gh);
 860   GNUNET_free (gh);
 861   gh = NULL;
 862   GNUNET_assert (!entry->in_lru);
 863   if ( (!entry->in_pool) && (NULL != map) )
 864   {
 865     if (GNUNET_YES == GNUNET_CONTAINER_multihashmap32_contains (map,
 866                                                                 entry->index))
 867       goto unallocate;
 868     if ((GNUNET_CONTAINER_multihashmap32_size (map) == max_size)
 869         && (NULL == head_lru))
 870       goto unallocate;
 871     destroy_pooled_connection (head_lru);
 872     GNUNET_CONTAINER_DLL_remove (head_not_pooled, tail_not_pooled, entry);
 873     GNUNET_assert (GNUNET_OK ==
 874                    GNUNET_CONTAINER_multihashmap32_put (map,
 875                                                         entry->index,
 876                                                         entry,
 877                                                         GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY));
 878     entry->in_pool = GNUNET_YES;
 879   }
 880  unallocate:
 881   GNUNET_assert (0 < entry->demand);
 882   entry->demand--;
 883   if (0 != entry->demand)
 884     return;
 885   if (entry->in_pool)
 886   {
 887     add_to_lru (entry);
 888     return;
 889   }
 890   destroy_pooled_connection (entry);
 891 }