1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
/*
This file is part of GNUnet.
Copyright (C) 2008--2015 GNUnet e.V.
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
Affero General Public License for more details.
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/>.
*/
/**
* @file testbed/gnunet-service-testbed_connectionpool.h
* @brief Interface for connection pooling subroutines
* @author Sree Harsha Totakura <sreeharsha@totakura.in>
*/
#include "gnunet_ats_service.h"
#include "gnunet_core_service.h"
#include "gnunet_transport_core_service.h"
/**
* The request handle for obtaining a pooled connection
*/
struct GST_ConnectionPool_GetHandle;
/**
* The type of service
*/
enum GST_ConnectionPool_Service
{
/**
* Transport service
*/
GST_CONNECTIONPOOL_SERVICE_TRANSPORT = 1,
/**
* Core service
*/
GST_CONNECTIONPOOL_SERVICE_CORE,
/**
* ATS service
*/
GST_CONNECTIONPOOL_SERVICE_ATS_CONNECTIVITY
};
/**
* Initialise the connection pool.
*
* @param size the size of the connection pool. Each entry in the connection
* pool can handle a connection to each of the services enumerated in
* #GST_ConnectionPool_Service
*/
void
GST_connection_pool_init (unsigned int size);
/**
* Cleanup the connection pool
*/
void
GST_connection_pool_destroy (void);
/**
* Functions of this type are called when the needed handle is available for
* usage. These functions are to be registered with the function
* GST_connection_pool_get_handle(). The corresponding handles will be set upon
* success. If they are not set, then it signals an error while opening the
* handles.
*
* @param cls the closure passed to GST_connection_pool_get_handle()
* @param ch the handle to CORE. Can be NULL if it is not requested
* @param th the handle to TRANSPORT. Can be NULL if it is not requested
* @param ac the handle to ATS, can be NULL if it is not requested
* @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
* cases, its value being NULL means that CORE connection has failed.
* @param cfg configuration of the peer
*/
typedef void
(*GST_connection_pool_connection_ready_cb) (void *cls,
struct GNUNET_CORE_Handle *ch,
struct GNUNET_TRANSPORT_CoreHandle *th,
struct GNUNET_ATS_ConnectivityHandle *ac,
const struct GNUNET_PeerIdentity *peer_id,
const struct GNUNET_CONFIGURATION_Handle *cfg);
/**
* Callback to notify when the target peer given to
* GST_connection_pool_get_handle() is connected.
*
* @param cls the closure given to GST_connection_pool_get_handle() for this
* callback
* @param target the peer identity of the target peer
*/
typedef void
(*GST_connection_pool_peer_connect_notify) (void *cls,
const struct GNUNET_PeerIdentity *target);
/**
* Get a connection handle to @a service. If the connection is opened before
* and the connection handle is present in the connection pool, it is returned
* through @a cb. @a peer_id is used for the lookup in the connection pool. If
* the connection handle is not present in the connection pool, a new connection
* handle is opened for the @a service using @a cfg. Additionally, @a target,
* @a connect_notify_cb can be specified to get notified when @a target is
* connected at @a service.
*
* @note @a connect_notify_cb will not be called if @a target is
* already connected @a service level. Use
* GNUNET_TRANSPORT_check_peer_connected() or a similar function from the
* respective @a service's API to check if the target peer is already connected or
* not. @a connect_notify_cb will be called only once or never (in case @a target
* cannot be connected or is already connected).
*
* @param peer_id the index of the peer
* @param cfg the configuration with which the transport handle has to be
* created if it was not present in the cache
* @param service the service of interest
* @param cb the callback to notify when the transport handle is available
* @param cb_cls the closure for @a cb
* @param target the peer identify of the peer whose connection to our TRANSPORT
* subsystem will be notified through the @a connect_notify_cb. Can be NULL
* @param connect_notify_cb the callback to call when the @a target peer is
* connected. This callback will only be called once or never again (in
* case the target peer cannot be connected). Can be NULL
* @param connect_notify_cb_cls the closure for @a connect_notify_cb
* @return the handle which can be used cancel or mark that the handle is no
* longer being used
*/
struct GST_ConnectionPool_GetHandle *
GST_connection_pool_get_handle (unsigned int peer_id,
const struct GNUNET_CONFIGURATION_Handle *cfg,
enum GST_ConnectionPool_Service service,
GST_connection_pool_connection_ready_cb cb,
void *cb_cls,
const struct GNUNET_PeerIdentity *target,
GST_connection_pool_peer_connect_notify connect_notify_cb,
void *connect_notify_cb_cls);
/**
* Relinquish a #GST_ConnectionPool_GetHandle object. If the connection
* associated with the object is currently being used by other
* #GST_ConnectionPool_GetHandle objects, it is left in the connection pool. If
* no other objects are using the connection and the connection pool is not full
* then it is placed in a LRU queue. If the connection pool is full, then
* connections from the LRU queue are evicted and closed to create place for this
* connection. If the connection pool if full and the LRU queue is empty, then
* the connection is closed.
*
* @param gh the handle
*/
void
GST_connection_pool_get_handle_done (struct GST_ConnectionPool_GetHandle *gh);
/* End of gnunet-service-testbed_connectionpool.h */
|
