2 This file is part of GNUnet.
3 Copyright (C) 2008--2013 Christian Grothoff (and other contributing authors)
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.
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.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @file testbed/gnunet-service-testbed_connectionpool.h
23 * @brief Interface for connection pooling subroutines
24 * @author Sree Harsha Totakura <sreeharsha@totakura.in>
29 * The request handle for obtaining a pooled connection
31 struct GST_ConnectionPool_GetHandle;
37 enum GST_ConnectionPool_Service
42 GST_CONNECTIONPOOL_SERVICE_TRANSPORT = 1,
47 GST_CONNECTIONPOOL_SERVICE_CORE
52 * Initialise the connection pool.
54 * @param size the size of the connection pool. Each entry in the connection
55 * pool can handle a connection to each of the services enumerated in
56 * #GST_ConnectionPool_Service
59 GST_connection_pool_init (unsigned int size);
63 * Cleanup the connection pool
66 GST_connection_pool_destroy ();
69 * Functions of this type are called when the needed handle is available for
70 * usage. These functions are to be registered with the function
71 * GST_connection_pool_get_handle(). The corresponding handles will be set upon
72 * success. If they are not set, then it signals an error while opening the
75 * @param cls the closure passed to GST_connection_pool_get_handle()
76 * @param ch the handle to CORE. Can be NULL if it is not requested
77 * @param th the handle to TRANSPORT. Can be NULL if it is not requested
78 * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
79 * cases, its value being NULL means that CORE connection has failed.
82 (*GST_connection_pool_connection_ready_cb) (void *cls,
83 struct GNUNET_CORE_Handle * ch,
84 struct GNUNET_TRANSPORT_Handle * th,
85 const struct GNUNET_PeerIdentity *
90 * Callback to notify when the target peer given to
91 * GST_connection_pool_get_handle() is connected.
93 * @param cls the closure given to GST_connection_pool_get_handle() for this
95 * @param target the peer identity of the target peer
98 (*GST_connection_pool_peer_connect_notify) (void *cls,
99 const struct GNUNET_PeerIdentity
104 * Get a connection handle to @a service. If the connection is opened before
105 * and the connection handle is present in the connection pool, it is returned
106 * through @a cb. @a peer_id is used for the lookup in the connection pool. If
107 * the connection handle is not present in the connection pool, a new connection
108 * handle is opened for the @a service using @a cfg. Additionally, @a target,
109 * @a connect_notify_cb can be specified to get notified when @a target is
110 * connected at @a service.
112 * @note @a connect_notify_cb will not be called if @a target is
113 * already connected @a service level. Use
114 * GNUNET_TRANSPORT_check_peer_connected() or a similar function from the
115 * respective @a service's API to check if the target peer is already connected or
116 * not. @a connect_notify_cb will be called only once or never (in case @a target
117 * cannot be connected or is already connected).
119 * @param peer_id the index of the peer
120 * @param cfg the configuration with which the transport handle has to be
121 * created if it was not present in the cache
122 * @param service the service of interest
123 * @param cb the callback to notify when the transport handle is available
124 * @param cb_cls the closure for @a cb
125 * @param target the peer identify of the peer whose connection to our TRANSPORT
126 * subsystem will be notified through the @a connect_notify_cb. Can be NULL
127 * @param connect_notify_cb the callback to call when the @a target peer is
128 * connected. This callback will only be called once or never again (in
129 * case the target peer cannot be connected). Can be NULL
130 * @param connect_notify_cb_cls the closure for @a connect_notify_cb
131 * @return the handle which can be used cancel or mark that the handle is no
134 struct GST_ConnectionPool_GetHandle *
135 GST_connection_pool_get_handle (unsigned int peer_id,
136 const struct GNUNET_CONFIGURATION_Handle *cfg,
137 enum GST_ConnectionPool_Service service,
138 GST_connection_pool_connection_ready_cb cb,
140 const struct GNUNET_PeerIdentity *target,
141 GST_connection_pool_peer_connect_notify connect_notify_cb,
142 void *connect_notify_cb_cls);
146 * Relinquish a #GST_ConnectionPool_GetHandle object. If the connection
147 * associated with the object is currently being used by other
148 * #GST_ConnectionPool_GetHandle objects, it is left in the connection pool. If
149 * no other objects are using the connection and the connection pool is not full
150 * then it is placed in a LRU queue. If the connection pool is full, then
151 * connections from the LRU queue are evicted and closed to create place for this
152 * connection. If the connection pool if full and the LRU queue is empty, then
153 * the connection is closed.
155 * @param gh the handle
158 GST_connection_pool_get_handle_done (struct GST_ConnectionPool_GetHandle *gh);
161 /* End of gnunet-service-testbed_connectionpool.h */