include/ctdb.h

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