prelude-connection-pool: libprelude Reference Manual

## prelude-connection-pool prelude-connection-pool |

## Functions

void | prelude_connection_pool_broadcast ()
void | prelude_connection_pool_broadcast_async ()
int | prelude_connection_pool_init ()
int | prelude_connection_pool_new ()
prelude_connection_pool_t * | prelude_connection_pool_ref ()
prelude_list_t * | prelude_connection_pool_get_connection_list ()
int | prelude_connection_pool_add_connection ()
int | prelude_connection_pool_del_connection ()
int | prelude_connection_pool_set_connection_dead ()
int | prelude_connection_pool_set_connection_alive ()
int | prelude_connection_pool_set_connection_string ()
const char * | prelude_connection_pool_get_connection_string ()
void | prelude_connection_pool_destroy ()
prelude_connection_pool_flags_t | prelude_connection_pool_get_flags ()
void | prelude_connection_pool_set_flags ()
void | prelude_connection_pool_set_required_permission ()
void | prelude_connection_pool_set_data ()
void * | prelude_connection_pool_get_data ()
int | prelude_connection_pool_recv ()
int | prelude_connection_pool_check_event ()
void | prelude_connection_pool_set_global_event_handler ()
void | prelude_connection_pool_set_event_handler ()

## Types and Values

enum | prelude_connection_pool_flags_t
enum | prelude_connection_pool_event_t
typedef | prelude_connection_pool_t

## Description

## Functions

### 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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
cnx | Pointer to a prelude_connection_t object used within `pool` . |

#### Returns

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

### prelude_connection_pool_set_connection_alive ()

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

Notifies `pool` that the connection identified by `cnx` went back alive.

Usually, this function should not be used since `pool` is self sufficient, and handles connection 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.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
cnx | Pointer to a prelude_connection_t object used within `pool` . |

#### Returns

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

### prelude_connection_pool_set_connection_string ()

    int
    prelude_connection_pool_set_connection_string
                                   (prelude_connection_pool_t *pool,
                                    const char *cfgstr);

Sets the connection string for `pool` . The connection string should be in the form of : "address". Special operand like || (OR) and && (AND), are also accepted: "address && address".

Where && means that alert sent using `pool` will go to both configured addresses, and || means that if the left address fails, the right address will be used.

prelude_connection_pool_init() should be used to initiates the connection.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
cfgstr | Connection string. |

#### Returns

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

### prelude_connection_pool_get_connection_string ()

    const char *
    prelude_connection_pool_get_connection_string
                                   (prelude_connection_pool_t *pool);

Used to query the connection string used by `pool` .

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |

#### Returns

The connection string.

### prelude_connection_pool_destroy ()

    void
    prelude_connection_pool_destroy (prelude_connection_pool_t *pool);

Destroys `pool` and all connections handled.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |

### prelude_connection_pool_get_flags ()

    prelude_connection_pool_flags_t
    prelude_connection_pool_get_flags (prelude_connection_pool_t *pool);

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |

#### Returns

the prelude_connection_pool_flags_t used in `pool` .

### prelude_connection_pool_set_flags ()

    void
    prelude_connection_pool_set_flags (prelude_connection_pool_t *pool,
                                       prelude_connection_pool_flags_t flags);

Sets `flags` within `pools` .

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
flags | Flags to use for `pool` . |

### prelude_connection_pool_set_required_permission ()

    void
    prelude_connection_pool_set_required_permission
                                   (prelude_connection_pool_t *pool,
                                    prelude_connection_permission_t req_perm);

### prelude_connection_pool_set_data ()

    void
    prelude_connection_pool_set_data (prelude_connection_pool_t *pool,
                                      void *data);

The user might use this function to associate data with `pool` . The data associated might be retrieved using `prelude_connection_pool_get_data()`.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
data | Pointer to user specific data. |

### prelude_connection_pool_get_data ()

    void *
    prelude_connection_pool_get_data (prelude_connection_pool_t *pool);

The user might use this function to query data associated with `pool` using `prelude_connection_pool_set_data()`.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |

#### Returns

the user data associated to `pool` .

### prelude_connection_pool_recv ()

    int
    prelude_connection_pool_recv (prelude_connection_pool_t *pool,
                                  int timeout,
                                  prelude_connection_t **outcon,
                                  prelude_msg_t **outmsg);

This function queries the set of connections available in `pool` to see if events are waiting to be handled. If timeout is zero, then this function will return immediatly in case there is no event to be handled.

If timeout is -1, this function won't return until an event is available. Otherwise this function will return if there is no event after the specified number of second.

If an event is available, it will be read and store the prelude_connection_t object in the `outcon` pointer. If `outmsg` was specified, the message will be read and stored in there.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
timeout | Time to wait for an event. |
outcon | Pointer where the connection where an event happened should be stored. |
outmsg | Pointer where the next message that will be read should be stored. |

#### Returns

The number of handled events (0 or 1) or a negative value if an error occured.

### prelude_connection_pool_check_event ()

    int
    prelude_connection_pool_check_event (prelude_connection_pool_t *pool,
                                         int timeout,
                                         int (*event_cb) (prelude_connection_pool_t *pool, prelude_connection_pool_event_t event, prelude_connection_t *cnx, void *extra),
                                         void *extra);

This function queries the set of connections available in `pool` to see if events are waiting to be handled. If timeout is zero, then this function will return immediatly in case there is no event to be handled.

If timeout is -1, this function won't return until an event is available. Otherwise this function will return if there is no event after the specified number of second.

For each event, `event_cb` is called with the concerned `pool` , the provided `extra` data, and the `cnx` where an event has occured.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
timeout | Time to wait for an event. |
event_cb | User provided callback function to call on received events. |
extra | Pointer to user specific data provided to `event_cb` . |

#### Returns

The number of handled events, or a negative value if an error occured.

### prelude_connection_pool_set_global_event_handler ()

    void
    prelude_connection_pool_set_global_event_handler
                                   (prelude_connection_pool_t *pool,
                                    prelude_connection_pool_event_t wanted_events,
                                    int (*callback) (prelude_connection_pool_t *pool, prelude_connection_pool_event_t events));

`callback` will be called each time one of the event specified in `wanted_events` happen to `pool` . However, contrary to `prelude_connection_pool_set_event_handler()`, the callback will be called only once per set of event.

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
wanted_events | Event the user want to be notified about. |
callback | User specific callback to call when an event is available. |

### prelude_connection_pool_set_event_handler ()

    void
    prelude_connection_pool_set_event_handler
                                   (prelude_connection_pool_t *pool,
                                    prelude_connection_pool_event_t wanted_events,
                                    int (*callback) (prelude_connection_pool_t *pool, prelude_connection_pool_event_t events, prelude_connection_t *cnx));

`callback` will be called each time one of the event specified in `wanted_events` happens to `pool` .

#### Parameters

pool | Pointer to a prelude_connection_pool_t object. |
wanted_events | Event the user want to be notified about. |
callback | User specific callback to call when an event is available. |

## Types and Values

### enum prelude_connection_pool_flags_t

#### Members

PRELUDE_CONNECTION_POOL_FLAGS_RECONNECT |  |
PRELUDE_CONNECTION_POOL_FLAGS_FAILOVER |  |

### enum prelude_connection_pool_event_t

#### Members

PRELUDE_CONNECTION_POOL_EVENT_INPUT |  |
PRELUDE_CONNECTION_POOL_EVENT_DEAD |  |
PRELUDE_CONNECTION_POOL_EVENT_ALIVE |  |

### prelude_connection_pool_t

    typedef struct prelude_connection_pool prelude_connection_pool_t;