/*
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 .
SPDX-License-Identifier: AGPL3.0-or-later
*/
/**
* @file testbed/gnunet-service-testbed_connectionpool.h
* @brief Interface for connection pooling subroutines
* @author Sree Harsha Totakura
*/
#include "gnunet_ats_service.h"
#include "gnunet_core_service.h"
#include "gnunet_transport_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 */