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 serverid ports
 149 */
 150 /*
 151    a message handler ID meaning "give me all messages"
 152  */
 153 #define CTDB_SRVID_ALL (~(uint64_t)0)
 154
 155 /*
 156    The top 32 bits of the server id represents the owner of
 157    this part of the srvid space
 158 */
 159 #define CTDB_SRVID_MASK 0xFFFFFFFF00000000LL
 160
 161
 162 /*
 163    Samba owns all message handler IDs where the top 32 bits are all zero
 164 */
 165 #define CTDB_SRVID_SAMBA        0x0000000000000000
 166 #define CTDB_IS_SAMBA_SRVID     ((srvid & CTDB_SRVID_MASK) == CTDB_SRVID_SAMBA)
 167
 168 /*
 169    Server ids reserved for testing
 170 */
 171 #define CTDB_SRVID_TEST         0x0000000100000000
 172 #define CTDB_IS_TEST_SRVID      ((srvid & CTDB_SRVID_MASK) == CTDB_SRVID_TEST)
 173
 174 /*
 175   srvid type : RECOVERY
 176 */
 177 #define CTDB_SRVID_RECOVERY     0xF100000000000000LL
 178
 179 /*
 180    a message handler ID meaning that the cluster has been reconfigured
 181  */
 182 #define CTDB_SRVID_RECONFIGURE 0xF200000000000000LL
 183
 184 /*
 185    a message handler ID meaning that an IP address has been released
 186  */
 187 #define CTDB_SRVID_RELEASE_IP 0xF300000000000000LL
 188
 189 /*
 190    a message ID to set the node flags in the recovery daemon
 191  */
 192 #define CTDB_SRVID_SET_NODE_FLAGS 0xF400000000000000LL
 193
 194 /*
 195    a message ID to ask the recovery daemon to update the expected node
 196    assignment for a public ip
 197  */
 198 #define CTDB_SRVID_RECD_UPDATE_IP 0xF500000000000000LL
 199
 200 /*
 201   a message to tell the recovery daemon to fetch a set of records
 202  */
 203 #define CTDB_SRVID_VACUUM_FETCH 0xF700000000000000LL
 204
 205 /*
 206   a message to tell the recovery daemon to write a talloc memdump
 207   to the log
 208  */
 209 #define CTDB_SRVID_MEM_DUMP 0xF800000000000000LL
 210
 211 /*
 212    a message ID to get the recovery daemon to push the node flags out
 213  */
 214 #define CTDB_SRVID_PUSH_NODE_FLAGS 0xF900000000000000LL
 215
 216 /*
 217    a message ID to get the recovery daemon to reload the nodes file
 218  */
 219 #define CTDB_SRVID_RELOAD_NODES 0xFA00000000000000LL
 220
 221 /*
 222    a message ID to get the recovery daemon to perform a takeover run
 223  */
 224 #define CTDB_SRVID_TAKEOVER_RUN 0xFB00000000000000LL
 225
 226 /* A message id to ask the recovery daemon to temporarily disable the
 227    public ip checks
 228 */
 229 #define CTDB_SRVID_DISABLE_IP_CHECK  0xFC00000000000000LL
 230
 231 /* A dummy port used for sending back ipreallocate resposnes to the main
 232    daemon
 233 */
 234 #define CTDB_SRVID_TAKEOVER_RUN_RESPONSE  0xFD00000000000000LL
 235
 236 /* A port reserved for samba (top 32 bits)
 237  */
 238 #define CTDB_SRVID_SAMBA_NOTIFY  0xFE00000000000000LL
 239
 240 /*
 241  * messaging functions
 242  * these functions provide a messaging layer for applications to communicate
 243  * with eachother across
 244  */
 245 typedef void (*ctdb_message_fn_t)(struct ctdb_context *, uint64_t srvid, TDB_DATA data, void *);
 246
 247 /*
 248  * register a message handler and start listening on a service port
 249  */
 250 typedef void (*ctdb_set_message_handler_cb)(int32_t status, void *private_data);
 251
 252 ctdb_handle *
 253 ctdb_set_message_handler_send(struct ctdb_context *ctdb, uint64_t srvid,
 254                               ctdb_set_message_handler_cb callback,
 255                               ctdb_message_fn_t handler, void *private_data);
 256
 257 int ctdb_set_message_handler_recv(struct ctdb_context *ctdb,
 258                                   ctdb_handle *handle);
 259
 260 int ctdb_set_message_handler(struct ctdb_context *ctdb, uint64_t srvid,
 261                              ctdb_message_fn_t handler, void *private_data);
 262
 263
 264
 265 /*
 266  * unregister a message handler and stop listening on teh specified port
 267  */
 268 typedef void (*ctdb_remove_message_handler_cb)(int32_t status, void *private_data);
 269
 270 ctdb_handle *
 271 ctdb_remove_message_handler_send(struct ctdb_context *ctdb, uint64_t srvid,
 272                                  ctdb_remove_message_handler_cb callback,
 273                                  void *private_data);
 274
 275 int ctdb_remove_message_handler_recv(struct ctdb_context *ctdb,
 276                                   ctdb_handle *handle);
 277
 278 int ctdb_remove_message_handler(struct ctdb_context *ctdb, uint64_t srvid);
 279
 280
 281
 282 /*
 283  * send a message to a specific node/port
 284  * this function is non-blocking
 285  */
 286 int ctdb_send_message(struct ctdb_context *ctdb, uint32_t pnn, uint64_t srvid, TDB_DATA data);
 287
 288
 289
 290
 291 /*
 292  * functions to read the pnn number of the local node
 293  */
 294 ctdb_handle *
 295 ctdb_getpnn_send(struct ctdb_context *ctdb,
 296                  uint32_t destnode,
 297                  ctdb_generic_callback callback,
 298                  void *private_data);
 299 int ctdb_getpnn_recv(struct ctdb_context *ctdb,
 300                      ctdb_handle *handle,
 301                      uint32_t *pnn);
 302 int ctdb_getpnn(struct ctdb_context *ctdb,
 303                 uint32_t destnode,
 304                 uint32_t *pnn);
 305
 306
 307
 308
 309 /*
 310  * functions to read the recovery master of a node
 311  */
 312 ctdb_handle *
 313 ctdb_getrecmaster_send(struct ctdb_context *ctdb,
 314                         uint32_t destnode,
 315                         ctdb_generic_callback callback,
 316                         void *private_data);
 317 int ctdb_getrecmaster_recv(struct ctdb_context *ctdb,
 318                         ctdb_handle *handle,
 319                         uint32_t *recmaster);
 320 int ctdb_getrecmaster(struct ctdb_context *ctdb,
 321                         uint32_t destnode,
 322                         uint32_t *recmaster);
 323
 324
 325
 326
 327 /*
 328  * cancel a request/call or release a resource
 329  */
 330 int ctdb_free(ctdb_handle *);
 331
 332
 333
 334 #endif