include/ctdb.h

   1 /*
   2    ctdb database library
   3
   4    Copyright (C) Ronnie sahlberg 2010
   5    Copyright (C) Rusty Russell 2010
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program; if not, see <http://www.gnu.org/licenses/>.
  19 */
  20
  21 #ifndef _CTDB_H
  22 #define _CTDB_H
  23 #include <sys/types.h>
  24 #include <stdint.h>
  25 #include <tdb.h>
  26
  27 /* All *_send() functions are guaranteed to be non-blocking and fully
  28  * asynchronous.  The non-_send variants are synchronous. */
  29
  30 /*
  31  * Connect to ctdb using the specified domain socket.
  32  * Returns a ctdb context if successful or NULL.
  33  *
  34  * Use ctdb_free() to release the returned ctdb_connection when finished.
  35  */
  36 struct ctdb_connection *ctdb_connect(const char *addr);
  37
  38 int ctdb_get_fd(struct ctdb_connection *ctdb);
  39
  40 int ctdb_which_events(struct ctdb_connection *ctdb);
  41
  42 int ctdb_service(struct ctdb_connection *ctdb, int revents);
  43
  44 struct ctdb_request;
  45
  46 void ctdb_request_free(struct ctdb_request *req);
  47
  48 /*
  49  * Callback for completed requests: it would normally unpack the request
  50  * using ctdb_*_recv().  You must free the request using ctdb_request_free().
  51  *
  52  * Note that due to macro magic, your callback doesn't have to take void *,
  53  * it can take a type which matches the actual private parameter.
  54  */
  55 typedef void (*ctdb_callback_t)(struct ctdb_connection *ctdb,
  56                                 struct ctdb_request *req, void *private);
  57
  58 /*
  59  * Special node addresses :
  60  */
  61 /* used on the domain socket, send a pdu to the local daemon */
  62 #define CTDB_CURRENT_NODE     0xF0000001
  63 /* send a broadcast to all nodes in the cluster, active or not */
  64 #define CTDB_BROADCAST_ALL    0xF0000002
  65 /* send a broadcast to all nodes in the current vnn map */
  66 #define CTDB_BROADCAST_VNNMAP 0xF0000003
  67 /* send a broadcast to all connected nodes */
  68 #define CTDB_BROADCAST_CONNECTED 0xF0000004
  69
  70
  71 /*
  72  * functions to attach to a database
  73  * if the database does not exist it will be created.
  74  *
  75  * You have to free the handle with ctdb_detach_db() when finished with it.
  76  */
  77 struct ctdb_db;
  78
  79 struct ctdb_request *
  80 ctdb_attachdb_send(struct ctdb_connection *ctdb,
  81                    const char *name, int persistent, uint32_t tdb_flags,
  82                    ctdb_callback_t callback, void *private_data);
  83
  84 struct ctdb_db *ctdb_attachdb_recv(struct ctdb_request *req);
  85
  86 struct ctdb_db *ctdb_attachdb(struct ctdb_connection *ctdb,
  87                               const char *name, int persistent,
  88                               uint32_t tdb_flags);
  89
  90 struct ctdb_lock;
  91
  92 /*
  93  * functions to read a record from the database
  94  * when the callback is invoked, the client will hold an exclusive lock
  95  * on the record, the client MUST NOT block during holding this lock and MUST
  96  * release it quickly by performing ctdb_release_lock(lock).
  97  *
  98  * When the lock is released, data is freed too, so make sure to copy the data
  99  * before that.
 100  */
 101 struct ctdb_request *
 102 ctdb_readrecordlock_send(struct ctdb_db *ctdb_db, TDB_DATA key,
 103                          ctdb_callback_t callback, void *private_data);
 104 struct ctdb_lock *ctdb_readrecordlock_recv(struct ctdb_db *ctdb_db,
 105                                            struct ctdb_request *handle,
 106                                            TDB_DATA *data);
 107
 108 /* Returns null on failure. */
 109 struct ctdb_lock *ctdb_readrecordlock(struct ctdb_db *ctdb_db, TDB_DATA key,
 110                                       TDB_DATA *data);
 111
 112 /*
 113  * Function to write data to a record
 114  * This function may ONLY be called while holding a lock to the record
 115  * created by ctdb_readrecordlock*
 116  * Either from the callback provided to ctdb_readrecordlock_send()
 117  * or after calling ctdb_readrecordlock_recv() but before calling
 118  * ctdb_release_lock() to release the lock.
 119  */
 120 int ctdb_writerecord(struct ctdb_lock *lock, TDB_DATA data);
 121
 122
 123 void ctdb_release_lock(struct ctdb_lock *lock);
 124
 125 /*
 126  * messaging functions
 127  * these functions provide a messaging layer for applications to communicate
 128  * with eachother across
 129  */
 130 typedef void (*ctdb_message_fn_t)(struct ctdb_connection *, uint64_t srvid, TDB_DATA data, void *);
 131
 132 struct ctdb_request *
 133 ctdb_set_message_handler_send(struct ctdb_connection *ctdb, uint64_t srvid,
 134                               ctdb_message_fn_t handler,
 135                               ctdb_callback_t callback,
 136                               void *private_data);
 137
 138 int ctdb_set_message_handler_recv(struct ctdb_connection *ctdb,
 139                                   struct ctdb_request *handle);
 140
 141 int ctdb_set_message_handler(struct ctdb_connection *ctdb, uint64_t srvid,
 142                              ctdb_message_fn_t handler, void *private_data);
 143
 144
 145
 146 /*
 147  * unregister a message handler and stop listening on teh specified port
 148  */
 149 struct ctdb_request *
 150 ctdb_remove_message_handler_send(struct ctdb_connection *ctdb, uint64_t srvid,
 151                                  ctdb_callback_t callback,
 152                                  void *private_data);
 153
 154 int ctdb_remove_message_handler_recv(struct ctdb_request *handle);
 155
 156 int ctdb_remove_message_handler(struct ctdb_connection *ctdb, uint64_t srvid);
 157
 158
 159
 160 /*
 161  * send a message to a specific node/port
 162  * this function is non-blocking
 163  */
 164 int ctdb_send_message(struct ctdb_connection *ctdb, uint32_t pnn, uint64_t srvid, TDB_DATA data);
 165
 166
 167
 168 /*
 169  * functions to read the pnn number of the local node
 170  */
 171 struct ctdb_request *
 172 ctdb_getpnn_send(struct ctdb_connection *ctdb,
 173                  uint32_t destnode,
 174                  ctdb_callback_t callback,
 175                  void *private_data);
 176 int ctdb_getpnn_recv(struct ctdb_request *req, uint32_t *pnn);
 177
 178 int ctdb_getpnn(struct ctdb_connection *ctdb,
 179                 uint32_t destnode,
 180                 uint32_t *pnn);
 181
 182
 183
 184
 185 /*
 186  * functions to read the recovery master of a node
 187  */
 188 struct ctdb_request *
 189 ctdb_getrecmaster_send(struct ctdb_connection *ctdb,
 190                         uint32_t destnode,
 191                         ctdb_callback_t callback,
 192                         void *private_data);
 193 int ctdb_getrecmaster_recv(struct ctdb_request *handle,
 194                            uint32_t *recmaster);
 195 int ctdb_getrecmaster(struct ctdb_connection *ctdb,
 196                         uint32_t destnode,
 197                         uint32_t *recmaster);
 198
 199
 200
 201
 202 /*
 203  * cancel a request
 204  */
 205 int ctdb_cancel(struct ctdb_request *);
 206
 207
 208 /* These ugly macro wrappers make the callbacks typesafe. */
 209 #include <ccan/typesafe_cb.h>
 210 #define ctdb_sendcb(cb, cbdata)                                         \
 211          typesafe_cb_preargs(void, (cb), (cbdata),                      \
 212                              struct ctdb_connection *, struct ctdb_request *)
 213
 214 #define ctdb_attachdb_send(ctdb, name, persistent, tdb_flags, cb, cbdata) \
 215         ctdb_attachdb_send((ctdb), (name), (persistent), (tdb_flags),   \
 216                            ctdb_sendcb((cb), (cbdata)), (cbdata))
 217
 218 #define ctdb_readrecordlock_send(ctdb_db, key, cb, cbdata)              \
 219         ctdb_readrecordlock_send((ctdb_db), (key),                      \
 220                                  ctdb_sendcb((cb), (cbdata)), (cbdata))
 221
 222 #define ctdb_set_message_handler_send(ctdb, srvid, handler, cb, cbdata) \
 223         ctdb_set_message_handler_send((ctdb), (srvid), (handler),       \
 224               ctdb_sendcb((cb), (cbdata)), (cbdata))
 225
 226 #define ctdb_remove_message_handler_send(ctdb, srvid, cb, cbdata)       \
 227         ctdb_remove_message_handler_send((ctdb), (srvid),               \
 228               ctdb_sendcb((cb), (cbdata)), (cbdata))
 229
 230 #define ctdb_getpnn_send(ctdb, destnode, cb, cbdata)                    \
 231         ctdb_getpnn_send((ctdb), (destnode),                            \
 232                          ctdb_sendcb((cb), (cbdata)), (cbdata))
 233
 234 #define ctdb_getrecmaster_send(ctdb, destnode, cb, cbdata)              \
 235         ctdb_getrecmaster_send((ctdb), (destnode),                      \
 236                                ctdb_sendcb((cb), (cbdata)), (cbdata))
 237 #endif