prelude-connection-pool

prelude-connection-pool — Pool of connection handling

Synopsis

enum                prelude_connection_pool_flags_t;
enum                prelude_connection_pool_event_t;
typedef             prelude_connection_pool_t;
void                prelude_connection_pool_broadcast   (prelude_connection_pool_t *pool,
                                                         prelude_msg_t *msg);
void                prelude_connection_pool_broadcast_async
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_msg_t *msg);
int                 prelude_connection_pool_init        (prelude_connection_pool_t *pool);
int                 prelude_connection_pool_new         (prelude_connection_pool_t **ret,
                                                         prelude_client_profile_t *cp,
                                                         prelude_connection_permission_t permission);
prelude_connection_pool_t * prelude_connection_pool_ref (prelude_connection_pool_t *pool);
prelude_list_t *    prelude_connection_pool_get_connection_list
                                                        (prelude_connection_pool_t *pool);
int                 prelude_connection_pool_add_connection
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);
int                 prelude_connection_pool_del_connection
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);
int                 prelude_connection_pool_set_connection_dead
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);
int                 prelude_connection_pool_set_connection_alive
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);
int                 prelude_connection_pool_set_connection_string
                                                        (prelude_connection_pool_t *pool,
                                                         const char *cfgstr);
const char *        prelude_connection_pool_get_connection_string
                                                        (prelude_connection_pool_t *pool);
void                prelude_connection_pool_destroy     (prelude_connection_pool_t *pool);
prelude_connection_pool_flags_t  prelude_connection_pool_get_flags
                                                        (prelude_connection_pool_t *pool);
void                prelude_connection_pool_set_flags   (prelude_connection_pool_t *pool,
                                                         prelude_connection_pool_flags_t flags);
void                prelude_connection_pool_set_required_permission
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_permission_t req_perm);
void                prelude_connection_pool_set_data    (prelude_connection_pool_t *pool,
                                                         void *data);
void *              prelude_connection_pool_get_data    (prelude_connection_pool_t *pool);
int                 prelude_connection_pool_recv        (prelude_connection_pool_t *pool,
                                                         int timeout,
                                                         prelude_connection_t **outcon,
                                                         prelude_msg_t **outmsg);
int                 prelude_connection_pool_check_event (prelude_connection_pool_t *pool,
                                                         int timeout,
                                                         int (event_cbprelude_connection_pool_t *pool,prelude_connection_pool_event_t event,prelude_connection_t *cnx, void *extra) (),
                                                         void *extra);
void                prelude_connection_pool_set_global_event_handler
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_pool_event_t wanted_events,
                                                         int (callbackprelude_connection_pool_t *pool,prelude_connection_pool_event_t events) ());
void                prelude_connection_pool_set_event_handler
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_pool_event_t wanted_events,
                                                         int (callbackprelude_connection_pool_t *pool,prelude_connection_pool_event_t events,prelude_connection_t *cnx) ());

Description

This API handle pool of connection, allowing to address a set of connection using only one object.

AND & OR of connection are supported, so that it is possible to address several connection at once, or to only address a set of connection if another connection went down.

Additionally it provide failover in case one of the connection in the pool goes down, and automatic reconnection and flushing of the information that could not be sent due to the connection status.

It is usually not necessary to access this API directly, however if you are looking at how to read events from a pool of connection, you're most probably looking for the prelude_connection_pool_check_event() function.

If this is the case, use prelude_connection_pool_check_event() for polling the pool or prelude_connection_set_event_handler() / prelude_connection_set_global_event_handler() if you want asynchronous notification of event.

Note that prelude_connection_set_event_handler() and prelude_connection_set_global_event_handler() are only asynchronous if timer are running in asynchronous mode. Otherwise, the callback for theses function might be called when you call the prelude_timer_wake_up() function.

In the provided callback, you might use prelude_connection_recv() to retrieve an event of type PRELUDE_CONNECTION_POOL_EVENT_INPUT. And, you could, for example, if the retrieved message has the PRELUDE_MSG_ID_IDMEF tag, provide the returned prelude_msg_t object to idmef_message_read() in order to convert the received message to a idmef_message_t object.

Details

enum prelude_connection_pool_flags_t

typedef enum {
        PRELUDE_CONNECTION_POOL_FLAGS_RECONNECT        = 0x01,
        PRELUDE_CONNECTION_POOL_FLAGS_FAILOVER         = 0x02
} prelude_connection_pool_flags_t;

enum prelude_connection_pool_event_t

typedef enum {
        PRELUDE_CONNECTION_POOL_EVENT_INPUT            = 0x01,
        PRELUDE_CONNECTION_POOL_EVENT_DEAD             = 0x02,
        PRELUDE_CONNECTION_POOL_EVENT_ALIVE            = 0x04
} prelude_connection_pool_event_t;

prelude_connection_pool_t

typedef struct prelude_connection_pool prelude_connection_pool_t;

prelude_connection_pool_broadcast ()

void                prelude_connection_pool_broadcast   (prelude_connection_pool_t *pool,
                                                         prelude_msg_t *msg);

Sends the message contained in msg to all the connection in pool.

pool :

 Pointer to a prelude_connection_pool_t object.

msg :

 Pointer on a prelude_msg_t object.

prelude_connection_pool_broadcast_async ()

void                prelude_connection_pool_broadcast_async
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_msg_t *msg);

Sends the message contained in msg to all connections in pool asynchronously. After the request is processed, the msg message will be freed.

pool :

 Pointer to a prelude_connection_pool_t object

msg :

 Pointer on a prelude_msg_t object.

prelude_connection_pool_init ()

int                 prelude_connection_pool_init        (prelude_connection_pool_t *pool);

Initializes pool. This means that connection associated with pool using prelude_connection_pool_set_connection_string() will be established.

pool :

 Pointer to a prelude_connection_pool_t object.

Returns :

 0 on success, a negative value on error.

prelude_connection_pool_new ()

int                 prelude_connection_pool_new         (prelude_connection_pool_t **ret,
                                                         prelude_client_profile_t *cp,
                                                         prelude_connection_permission_t permission);

prelude_connection_pool_new() initializes a new Connection Manager object.

ret :

 Pointer to an address where to store the created prelude_connection_pool_t object.

cp :

 The prelude_client_profile_t to use for connection.

permission :

 Permission the connection in this connection-pool will require.

Returns :

 0 on success or a negative value if an error occured.

prelude_connection_pool_ref ()

prelude_connection_pool_t * prelude_connection_pool_ref (prelude_connection_pool_t *pool);

Increases pool reference count.

prelude_connection_pool_destroy() will decrease the refcount until it reaches 0, at which point the pool will be destroyed.

pool :

 Pointer to a prelude_connection_pool_t object.

Returns :

 The provided pool is returned.

prelude_connection_pool_get_connection_list ()

prelude_list_t *    prelude_connection_pool_get_connection_list
                                                        (prelude_connection_pool_t *pool);

pool :

 Pointer to a prelude_connection_pool_t object.

Returns :

 The list of connections handled by pool.

prelude_connection_pool_add_connection ()

int                 prelude_connection_pool_add_connection
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);

Adds cnx to pool set of connections.

If pool is already initialized (prelude_connection_pool_init() called) and cnx is not alive, it will attempt a reconnection.

pool :

 Pointer to a prelude_connection_pool_t object.

cnx :

 Pointer to a prelude_connection_t object to add to pool.

Returns :

 0 on success, a negative value if an error occured.

prelude_connection_pool_del_connection ()

int                 prelude_connection_pool_del_connection
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);

Remove cnx from pool of connections.

pool :

 Pointer to a prelude_connection_pool_t object.

cnx :

 Pointer to a prelude_connection_t object to remove from pool.

Returns :

 0 on success, a negative value if an error occured.

prelude_connection_pool_set_connection_dead ()

int                 prelude_connection_pool_set_connection_dead
                                                        (prelude_connection_pool_t *pool,
                                                         prelude_connection_t *cnx);

Notifies pool that the connection identified by cnx is dead.

Usually, this function should not be used since pool is self sufficient, and handles connections issues internally. However, it is sometime useful when the user has several mechanisms using the connection, and that its own mechanism detects a connection problem before pool notice.

pool :

 Pointer to a prelude_connection_pool_t object.

cnx :

 Pointer to a prelude_connection_t object used within pool.

Returns :